/ 
Gtk2-Ex-TickerView-3
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::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 blob to go before every item.)

The display and scrolling direction follow the widget text direction of the set_direction method in 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 renderers is a matter for them. For example in Gtk2::CellRendererText Pango recognises right-to-left scripts such as Arabic based on the utf-8 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 child rows 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 can be given to set initial properties as per Glib::Object->new.

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

$ticker->scroll_to_start ()

Scroll the ticker contents back to the start, ie. the first row in the model.

OBJECT PROPERTIES

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

This is any 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 1)

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 calls 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 makes size negotiation with the ticker's container parent 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 function to suppress it just for selected items from the model.

BUILDABLE

Gtk2::Ex::TickerView implements the Gtk2::Buildable interface so Gtk2::Builder can be used to construct a TickerView. The class name is Gtk2__Ex__TickerView and renderers and attributes are added as per GtkCellLayout. Here's an example, or see examples/builder.pl in the Gtk2::Ex::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 with 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. Avoidance of 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 steps 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 have a description of exactly how pack_start and pack_end end up ordering 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 Gtk2::Ex::TickerView the ends immediately follow the starts (there's no gap in between, unlike say in a Gtk2::HBox).

SEE ALSO

Gtk2::CellLayout, Gtk2::TreeModel, Gtk2::CellRenderer