/ 
Gtk2-Ex-TickerView-4
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 rely only 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 scrolling text for example 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 be just a fixed image to go before every item.

The display and scrolling direction follow the text 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. So 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 a negative value goes backwards.

$n doesn't have to be an integer, the display position is maintained as a floating point value, allowing fractional amounts to 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 in the model at the left edge of the display (or right for rtl).

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 the screen 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 is speed divided by frame-rate many pixels.)

fixed-height-mode (boolean, default false)

If true then assume all rows in the model have the same height. This means the ticker can ask its renderers about just one row from the model, instead of going through all of them. If the model is big this is much faster.

The text direction giving the 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 setup func to suppress it just for selected items 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>

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.

Some care is taken drawing for scrolling. If unobscured then scrolling uses "CopyArea" and a draw of just the balance at the end. To avoid hammering the X server any further scroll waits until hearing from the server that the last completed (a NoExpose event normally). If partly obscured then alas plain full redraws must be used, though working progressively by cell to reduce flashing. Avoiding hammering is left up to queue_draw in that case. The effect of all this is probably only noticeable if your frame-rate is a bit too high or the server is lagged by other operations.

Scroll moves are always spun through an idle handler too, at roughly GDK_PRIORITY_REDRAW priority since they represent redraws, the aim being to collapse multiple MotionNotify events from a user drag, or multiple programmatic scroll_pixels calls from slack application code.

The Gtk reference documentation for GtkCellLayout doesn't describe exactly 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", the starts are drawn from the left, the ends are drawn from the right. In a TickerView the ends immediately follow the starts, there's no gap in between, unlike say in a Gtk2::HBox. See examples/order.pl for a demonstration.

When the model has no rows the TickerView has a desired height of zero. This is a pest if you want a visible but blank area when there's nothing to display. But there's no way the TickerView can work out a height when it's got no data at all to set the renderers. You might like to try calculating a fixed size from a dummy model and use set_size_request to force the height, or alternately have a "no data" row 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.

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

LICENSE

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/.