===============================
Python GGI Module documentation
===============================

Base packages
=============

The GGI Package
~~~~~~~~~~~~~~~

.. manpage:: 3 py.GGI

Description
-----------

This module provides access to several libraries developed by the GGI
project through an elegant and effective (in the author opinion)
python interface.

Note that most object in this wrappers are implemented as built-in C
types. Almost all attributes setting and retrieving operations will
actually call an underlying library function. This means that setting
attributes doesn't always succeed, and, if it does, the value set
might have be different from the one given.  This also means the
members and methods are invisible by the dir() built-in function.

Quickstart
----------

::

  #!/usr/bin/python
  from GGI import ggi
  from GGI.const import evKeyPress

  v = ggi.Visual()
  v.mode = v.Mode()
  v.putString(0,0,"hey, It worked!")
  v.wait(evKeyPress)
  #end


Modules
-------

The GGI package contains the following modules:


`GGI.const`
	Constant used in GGI, such as event code.
`GGI.exception`
	Exceptions used in Piggy.
`GGI.ascii`
	ASCII character map.
`GGI.keyboard`
	keyboard related constant, especially useful for handling
	key events.
`GGI.gii`
	Entry point to the libgii interface. This module defines
	two types, `Event` and `Input`, which are discussed later.
`GGI.ggi`
	Entry point to the libggi interface. This module defines
	three types, `Mode`, `Pack` and `Visual`, which are discussed later.
`GGI.ft2`
	Provide a rather complete interface to the Freetype library.
	Not documented yet.

GGI.gii.Event
~~~~~~~~~~~~~

.. manpage:: 3 py.GGI.gii.Event


Description
-----------

Event objects are used to store events sent to an application via Input
or Visual object.

Members
-------

`type`
	The exact event type. Depending on this value, different slots
	will be available for read and write. See `GGI.const` for the
	available types.
`error`
	An error code set by a device when replying to a command.
`time`
	The time at which this event was generated. It is given in
	seconds as a floating point value.
`origin`
	The device that generated this event, in case of a normal
        event. In case of a user event, it can be `evOriginNone`
        (anonymous event) or `evOriginSendEvent` (normal user event
        injected in the queue).
`target`
	The target of this event. It is used when sending event sent
        to the queue. It can be one of `evTargetQueue` (this event is
        queued normally), `evTargetAll` (the event is sent to each
        device) or an origin (the event is sent only to the designated
        device).
`size`
	The size of this event. This value is read-only. It is
	automatically updated when the event is altered.

Key
...

`modifiers`
	The modifiers that were active when the event occurred.
`symbol`
	The resultant character produced by the key.
`label`
	Can be used as a generalized, portable keycode or
	scancode of the key.  
`button`
	The scancode of the key.

Pointer
.......

`x`, `y`, `z`, `wheel`
        The pointer motion, either absolute or relative, in
	the 4 possible dimensions of the device.
`button`
	The number of the button which changed state.  For
	mouse buttons, the constant pbuttonLeft, pbuttonMiddle
        and pbuttonRight are defined.


Valuators
.........

`first`
	The index of the first valuator for which values are
	reported in the event.
`count`
	A read-only field that gives the number of values
	reported in this event. It cannot exceed 32.
`value`
	An array holding the reported values. The length is equal to
	`count`. The value can be set by giving a list of integer with
	a maximum of 32 values. The values are affected and the count
	field is updated.

Expose
......

`x`, `y`, `w`, `h`
        The bounding box of the area that needs to be repainted.

Command and Information
.......................

`code`
	The command code. Useful ones are those with the cmd-
	prefix and flagged by the `cmdflag-` constants in the
	`GGI.const` namespace.
`data`
	A binary string associated with the command. It is
	only available if the code doesn't have the
        `cmdflagNoData` bit set. Setting the data will update
        the size of the event.

Methods
-------

This class has no specific method.








GGI.gii.Input
~~~~~~~~~~~~~

.. manpage:: 3 py.GGI.gii.Input


Description
-----------

An Input object is the equivalent of the gii_input_t abstraction. It
serves as event provider to the application.

Members
-------

`mask`
	The current event mask that the Input must report.
`devices`
	A list of all devices attached to this Input.
	Each entry is defined as follow:
	
	- The input origin,
	- The device origin within this input,
	- The short name of the device,
	- A more explicit name,
	- The number of buttons,
	- The number of axes.

	This list is read-only. It is actually dynamically constructed
	on request, and will change if a device is detached for some
	reason.

Methods
-------

`poll([timeout=-1 [,mask=GGI.emAll]])`
	If the timeout is omitted or negative, the function will
	block until an event within the given mask becomes available. It
	returns a mask of events that are ready to be read.

	If a timeout is specified, the function will raise a
	`GGI.exception.Timeout` exception if no event occurred
	before the timeout expires. In the other case, it returns a
	tuple containing the mask of events that are ready to be read
	and the remaining time in seconds as a floating point value.

	Note that this function will not remove any event from the
	queue. It is also the only time when devices will be given
	a chance to queue new events to the input.
`queued([mask=GGI.emAll])`
	Returns the number of events within the given mask waiting to
	be read from this input. This function will not poll any input
	source.
`read([mask=GGI.emAll [,event=None]])`
	This function is used to retrieve events queued on the Input.
	The first event (earliest) matching the mask will be un-queued
	and returned as an Event object. Optionally, an Event object
	may be specified, in which case, it will be reused to store
	the new event, so that no memory allocation occurs.

	The function will return None if there is no event available.
`send(event)`
	The given event will be queued on the input, or delivered to
	a specific device depending to its target field. The function
	doesn't return any value.
`split(origin)`
	Constructs a new Input object containing the input source
	designated by the given origin. This input source is detached
	from the original Input object which may become invalid, as
	explained above.
`join(input)`
	This function will transfer all input sources and queued events
	of `input` into this Input.

	Note that the Input object becomes invalid after the call
	returns, but is not deleted by python for implementation
	issues. It should not be used anymore, and it is advised to
	delete it explicitly with the `del` directive.


GGI.ggi.Mode
~~~~~~~~~~~~

.. manpage:: 3 py.GGI.ggi.Mode


Description
-----------

The Mode objects serve as containers to describe the attributes of a
visual.

Members
-------

`frames`
	Then number of frames for this visual.
`visible`
	The visible extent of the visual in pixels.
`virtual`
	The global size of the visual if it is larger then the
	visible screen. This can be used for scrolling or to keep
	off-screen buffers.
`size`
	The size in mm, if the target can provide it.
`graphtype`
	The mode of the visual. text, graphic, color-space...
`dpp`
	The number of dot per pixel.


Methods
-------

This class has no specific method.


GGI.ggi.Pack
~~~~~~~~~~~~

.. manpage:: 3 py.GGI.ggi.Pack

Description
-----------

A Pack is a binary container for target specific pixel array.
It is useful to store large portion of screen to restore it later.

A Pack always depends on a Visual. It will take a reference on the
Visual, which means that the Visual will not be destroyed (closed)
before all Pack depending on it are destroyed.

Members
-------

`length`
	A read-only member witch gives the number of pixels that this
	Pack contains.

Methods
-------

`unPack()`
	Will return a list of rgb-triplets, given as floating point values,
	that correspond to pixel contained in the Pack.


GGI.ggi.Visual
~~~~~~~~~~~~~~

.. manpage:: 3 py.GGI.ggi.Visual

Description
-----------

A Visual is a 2D surface that can be drawn upon and which receive user
events.

Members
-------

`bg`, `fg`
	The background color and foreground color respectively. They
	are read as a pixel value (integer), but can be set either as
	a pixel value, or as an rgb-triplet
`readFrame`, `writeFrame`, `displayFrame`
	Define which frame is used for read operations, write
	operation, and which one is currently visible respectively.
	It is only meaningful if the visual has more than one frame
	(see Mode.frames).  This can be used as storage area, or to
	implement double or triple buffering.
`mode`
	Returns a mode object corresponding to the current mode of the
	visual.  The resulting object is completely independent of the
	Visual. If assigned, it will set the underlying visual mode.
`flags`
	Set and get the visual special properties and features. See
	the GGI.const module for the list of available flags.
`clipping`
	The clipping area given as a (x1,y1,x2,y2) tuple. No drawing
	operation will occur outside of this area.
`origin`
	A couple of integers giving the position of the visible area
	relatively to the virtual area. This is only useful if the
	virtual area is larger than the visible one.
`charSize`
	A read-only tuple giving the width and height of the built-in
	font.  It is useful to implement simple text layout in both
	graphic and text mode.
`devices`, `mask`
	See the corresponding Input members.
`gamma`
	A read-write float triplet to get and set the gamma correction
	for each channel.

Methods
-------

Visual operations
.................

`Mode([string])`
	Construct a mode, optionally initialized as specified by the
	string parameter, then check it against the visual. The
	resulting mode is fully specified (no AUTO value) and is
	guaranteed to be supported by the Visual. It might not
	correspond exactly to the requested mode though.
`Pack([size|pack|sequence])`
	Construct a new Pack for the Visual, and initialize it either
	from the values contained in an other pack (which may belong
	to another visual), or with the rgb-triplets contained in the
	given list. If the argument is an integer, the Pack will be created
	but not filled.
`flush([x1, y1, x2, y2])`
	Update the content of the screen within the given box, or the
	whole screen.
`map(r,g,b)`
	Convert a rgb-triplet (floating point values between 0 an 1)
	into the visual specific pixel value (integer).
`unMap(pixel)`
	Performs the reverse operation.
`getPixel(x, y)`
	Get the pixel at the given position and return the pixel value
	as an integer, suitable for `unMap` or drawing operations.
`getHLine(x, y, length, [pack])`
	Get an horizontal line of width w and returns a `Pack`
	containing the pixel values. If a `Pack` is provided, the
	values will be stored in there, and no Pack is allocated.
	The `Pack` must be big enough to contain all the values.
`getVLine(x, y, length, [pack])`
	Same as above, but with a vertical line of height h.
`getBox(x, y, width, height, [pack])`
	Same as above, with a box.

Drawing operations
..................

`fill([pixel|color])`
	Fill the screen with the given color (pixel or rgb-triplet) or with
	the current foreground color.
`putPixel(x, y,[pixel|color])`
	Put a pixel at the given position, using the foreground color
	if none is given. The color can be specified either as a pixel
	value or as a rgb-triplets.
`putLine(x1, y1, x2, y2, [pixel|color])`
  	Draws a line between the two specified point.
`putHLine(x, y, length, [pixel|color|pack])`
	Draws an horizontal line of width w. As above, the object can
	be a pixel value, a rgb-triplet, but also a Pack object.
	In this case, the data will be copied from the pack.
	The pack must contain enough data for the drawing operation.  
`putVLine(x, y, length, [pixel|color|pack])`
	Same as above, but draws a vertical line of height h.
`putBox(x, y, width, height, [pixel|color|pack])`
	Same as above, with a box.
`putString(x, y, s)`
	Write a string at the given position, using the built-in font
	face.  Only ASCII chars will be displayed. Complex font
	rendering is beyond the scope of the base API.
`copyBox([sx, sy, width, height, [dx, dy]])`
	Copy data from the given position and size, to the given
	destination. By default, it copies the whole screen between the
	read and the display frame. If `dx`, `dy` are not specified, the
	default destination is the same as the source.
`crossBlit(visual, [ x, y, w, h [, dx, dy ] ])`
	Same as above, but between two visuals.

Event management
................

`detach()`
	Create a new Input object which contains all input source
	bound to the visual. The visual becomes invalid as an event
	source. The input object must be used instead.
`join`, `read`, `poll`, `queued`, `send`
	See the corresponding Input methods

Available extensions
====================


Extending Piggy with C modules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 pyggi-extending

Introduction
------------

Coming soon...
