/ 
Gtk2-Ex-TickerView-7
River stage one • 1 direct dependent • 1 total dependent
/ Gtk2::Ex::TickerView

NAME

Gtk2::Ex::TickerView -- scrolling ticker display widget

SYNOPSIS

use Gtk2::Ex::TickerView;
my $ticker = Gtk2::Ex::TickerView->new (model => $model,
                                        ...);
my $renderer = Gtk2::CellRendererText->new;
$ticker->pack_start ($renderer, 0);
$ticker->set_attributes ($renderer, text => 0); # column

WIDGET HIERARCHY

Gtk2::Ex::TickerView is a subclass of Gtk2::DrawingArea, but that might change so it's recommended you only rely on Gtk2::Widget.

Gtk2::Widget
  Gtk2::DrawingArea
    Gtk2::Ex::TickerView

The interfaces implemented are:

Gtk2::Buildable
Gtk2::CellLayout

DESCRIPTION

A Gtk2::Ex::TickerView widget displays items from a Gtk2::TreeModel scrolling horizontally across the window, like a news bar or stock ticker.

+----------------------------------------------------------+
| st item  * The second item  * The third item   * The fou |
+----------------------------------------------------------+
    <---- scrolling

Items are drawn using one or more Gtk2::CellRenderer objects set into the TickerView as per the Gtk2::CellLayout interface. For example for scrolling text you can use Gtk2::CellRendererText.

If two or more renderers are set then they're drawn one after the other for each item, ie. row of the model. For example you could have a Gtk2::CellRendererPixbuf to draw an icon then a Gtk2::CellRendererText to draw some text and they scroll across together. The icon could use the model's data, or just be a fixed image to go before every item.

The display and scrolling direction follow set_direction (see Gtk2::Widget). For ltr mode item 0 starts at the left of the window and items scroll to the left. For rtl item 0 starts at the right of the window and items scroll to the right.

+----------------------------------------------------------+
| m five  * item four  * item three  * item two  * item on |
+----------------------------------------------------------+
                    right to left mode, scrolling ----->

Any text or drawing direction within each cell is a matter for the renderers. For example in Gtk2::CellRendererText Pango recognises right-to-left scripts such as Arabic based on the characters and shouldn't need any special setups.

Currently only a list style model is expected, meaning only a single level, and only that topmost level of the model is drawn. For example a Gtk2::ListStore suits. Perhaps in the future something will be done to descend into and draw subrows too.

The whole Gtk model/view/layout/renderer/attributes as used here is ridiculously complicated. Its power comes when showing a big updating list or wanting customized drawing, but the amount of code to get something on the screen is not nice. Have a look at "Tree and List Widget Overview" in the Gtk reference manual if you haven't already. Then examples/simple.pl in the TickerView sources is more or less the minimum to actually display something.

FUNCTIONS

Gtk2::Ex::TickerView->new (key => value, ...)

Create and return a new Gtk2::Ex::TickerView widget. Optional key/value pairs set initial properties as per Glib::Object->new (see Glib::Object).

$ticker->scroll_pixels ($n)

Scroll the ticker contents across by $n pixels. Postive $n moves in the normal scrolled direction or negative goes backwards.

$n doesn't have to be an integer, the display position is maintained as a floating point value so fractional amounts can accumulate until a whole pixel step is reached.

$ticker->scroll_to_start ()

Scroll the ticker contents back to the start, ie. to show the first row of the model at the left edge of the display (or right for rtl).

$path = $ticker->get_path_at_pos ($x, $y)

Return a Gtk2::TreePath which is the model row displayed at $x,$y, or return undef if there's nothing displayed there. There can be nothing if no model is set, or it has no rows, or all rows are zero width.

$x can be outside the window, the item which would be shown at that point is still returned. $y is currently ignored, since all items simply use the full window height. Perhaps in the future a $y outside the window height will cause an undef return.

OBJECT PROPERTIES

model (object implementing Gtk2::TreeModel, default undef)

This is any Glib::Object implementing the Gtk2::TreeModel interface, for example a Gtk2::ListStore. It supplies the data to be displayed. Until this is set the ticker is blank.

run (boolean, default true)

Whether to run the ticker, ie. to scroll it across under a timer. If false then the ticker just draws the items at its current position without moving (except by the programatic scroll functions above, or user dragging with mouse button 1).

speed (floating point pixels per second, default 25)

The speed the items scroll across, in pixels per second.

frame-rate (floating point frames per second, default 4)

The number of times each second the ticker moves and redraws. Each move will be speed divided by frame-rate many pixels.

The current current code uses the Glib main loop timer so the frame rate is turned into an integer number of milliseconds for actual use. A minimum 1 millisecond is imposed, meaning frame rates more than 1000 are treated as 1000. Of course 1000 frames a second is pointlessly high and almost certainly unattainable.

fixed-height-mode (boolean, default false)

If true then assume all rows in the model have the same height. This allows the ticker to get its desired height by asking the renderers about just one row of the model, instead of going through them all. If the model is big this is much faster.

The direction for display order and scrolling is not a property but instead accessed with the usual widget get_direction and set_direction methods (see Gtk2::Widget).

The visible property in each cell renderer is recognised and a renderer that's not visible is skipped and takes no space. Each visible can be set globally in the renderer to suppress it entirely, or controlled with the attributes mechanism or data func to suppress it just for selected rows from the model.

BUILDABLE

Gtk2::Ex::TickerView implements the Gtk2::Buildable interface, allowing Gtk2::Builder to construct a TickerView. The class name is Gtk2__Ex__TickerView and renderers and attributes are added as children per Gtk2::CellLayout. Here's a sample, or see examples/builder.pl in the TickerView sources for a complete program,

<object class="Gtk2__Ex__TickerView" id="myticker">
  <property name="model">myliststore</property>
  <child>
    <object class="GtkCellRendererText" id="myrenderer">
      <property name="xpad">10</property>
    </object>
    <attributes>
      <attribute name="text">0</attribute>
    </attributes>
  </child>
</object>

See "BUILDABLE INTERFACE" in Gtk2::Ex::CellLayout::Base for caveats about widget superclass tags which may end up unavailable.

OTHER NOTES

Mouse button 1 is setup for the user to drag the display back and forwards. This is good to go back and see something that's just moved off the edge, or to skip past boring bits. Perhaps in the future the button used will be customizable.

The Gtk reference documentation for GtkCellLayout doesn't really describe how pack_start and pack_end order cells, but it's the same as GtkBox and a description can be found there. Basically each cell is noted as "start" or "end", with starts drawn from the left and ends from the right (vice versa in RtoL mode). In a TickerView the ends immediately follow the starts, there's no gap in between, unlike say in a Gtk2::HBox. (Which means the "expand" parameter is ignored currently.) See examples/order.pl in the sources for a demonstration.

When the model has no rows the TickerView's desired height for size_request is zero. This is no good if you want a visible but blank area when there's nothing to display. But there's no way TickerView can work out a height when it's got no data at all to set into the renderers. You can try calculating a fixed height from a sample model and set_size_request to force that, or alternately have a "no data" row displaying in the model instead of letting it go empty, or even switch to a dummy model with a "no data" row when the real one is empty.

Drawing

Cells are drawn into an off-screen pixmap which is copied to the window at successively advancing X positions as the ticker scrolls across. The aim is to run the model fetching and cell rendering just once for each row as it appears on screen. (Rows wider than the pixmap will get multiple draws.)

The repeated drawing for scroll movement goes through a SyncCall (see Gtk2::Ex::SyncCall) so that after drawing one frame the next won't go out until hearing back from the server that it's finished the previous. This ensures a high frame rate doesn't flood the server with more drawing than it can keep up with.

Scroll movement amounts are calculated on elapsed time using clock_gettime() real time when available, or high-res system time otherwise (see Time::HiRes). This means the speed setting is followed even if the requested frame-rate is not being achieved. Slow frame rates can be caused on the client side if the main loop is busy doing other things (including temporarily blocked completely), or can be on the X server side if it's busy with other drawing.

SEE ALSO

Gtk2::CellLayout, Gtk2::TreeModel, Gtk2::CellRenderer, Gtk2::Ex::CellLayout::Base

HOME PAGE

http://www.geocities.com/user42_kevin/gtk2-ex-tickerview/index.html

COPYRIGHT

Copyright 2007, 2008 Kevin Ryde

Gtk2-Ex-TickerView is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Gtk2-Ex-TickerView is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Gtk2-Ex-TickerView. If not, see http://www.gnu.org/licenses/.