home *** CD-ROM | disk | FTP | other *** search
<?php /* vim: set expandtab tabstop=4 shiftwidth=4: */ // +----------------------------------------------------------------------+ // | PHP Version 4 | // +----------------------------------------------------------------------+ // | Copyright (c) 2004 The PHP Group | // +----------------------------------------------------------------------+ // | This source file is subject to version 3.0 of the PHP license, | // | that is bundled with this package in the file LICENSE, and is | // | available through the world-wide-web at the following url: | // | http://www.php.net/license/3_0.txt. | // | If you did not receive a copy of the PHP license and are unable to | // | obtain it through the world-wide-web, please send a note to | // | license@php.net so we can mail you a copy immediately. | // +----------------------------------------------------------------------+ // | Author: Scott Mattocks <scottmattocks@php.net> | // +----------------------------------------------------------------------+ // // $Id:$ /** * Gtk_ScrollingLabel * * This is a class to encapsulate the functionality * needed for a scrolling gtk label. This class * provides a simple, easy to understand API for * setting up and controlling the label. It allows * for the ability to scroll in either direction, * start and stop the scroll, pause and unpause the * scroll, get and set the text, and set display * properites of the text. * * @author Scott Mattocks * @category Gtk * @package ScrollingLabel * @license http://www.php.net/license/3_0.txt PHP License 3.0 * @copyright Copyright © 2004 Scott Mattocks * * @todo Allow text to wrap the visible area. */ /** * A constant for representing srolls that move from left to right * @const GTK_SCROLL_LEFT */ define('GTK_SCROLLINGLABEL_LEFT', 1); /** * A constant for representing srolls that move from right to left * @const GTK_SCROLLINGLABEL_RIGHT */ define('GTK_SCROLLINGLABEL_RIGHT', 2); /** * A SrollingLabel error code. * @const GTK_SCROLLINGLABEL_DEFAULT_ERROR */ define('GTK_SCROLLINGLABEL_DEFAULT_ERROR', 1); /** * Class for creating a label with the ability to scroll * text. */ class Gtk_ScrollingLabel { /** * The event box which will contain the label and listen for events. * @var object */ var $widget; /** * The label which will display the text. * @var object */ var $label; /** * The full text that will be displayed over time. * @var string */ var $labelText; /** * The tag returned to indicate the call to gtk timeout. * @var integer */ var $gtkTimeoutTag; /** * The number of characters that should be visible * @var integer */ var $visibleLength = 70; /** * The number of milliseconds between calls to the method passed * to gtk timeout. * @var integer */ var $speed = 70; /** * The first character to show when direction is GTK_SCROLLINGLABEL_LEFT * The last character to show when direction is GTK_SCROLLINGLABEL_RIGHT * @var integer */ var $currentCharPosition = 0; /** * The direction the text should be moving. * @var integer */ var $direction = GTK_SCROLLINGLABEL_LEFT; /** * Whether the text should change direction when it hits an edge. * @var boolean */ var $bounce = true; /** * Constructor. * Loads module if needed then builds needed widgets. * * @access private * @param string $startingText The text to display uppon creation. * @return void */ function Gtk_ScrollingLabel($startingText = '') { // Create a GTK_eventbox. // This is used to connect events to the label (Sort of). $this->widget =& new GtkEventBox; // We need to add an event mask for the event box. $this->widget->add_events(GDK_BUTTON_PRESS_MASK); // Next we need to create a label. $this->label =& new GtkLabel($startingText); $this->labelText = $startingText; // We need to set up some label stuff $this->label->set_alignment(0, 1.0); $this->label->set_usize(-1, 1); $this->label->set_justify(GTK_JUSTIFY_LEFT); // We need to set the direction of the scroll. $this->setDirection($this->direction); // Then we can cram the label into the event box. $this->widget->add($this->label); } /** * Display the visible text and de/increment the current position. * Needs to check if we are at the end of the string and which * direction the text is moving. * * This is the brains of the class. _scrollLabel figures out what * to do next. If we are scrolling in one direction we need to * know when the text has all passed through the visible "window" * so that we can start all over again. If we are bouncing the * text between the two edges of the visible window we need to * know when we have reached an edge so that the text can go in * the opposite direction next time. * * Note: If the text is set to bounce and the text is larger than * the visible window can display, the text will not bounce the * way one would expect. Larger than visible window text bouncing * may be supported later but that is not guaranteed. * * @access private * @param none * @return boolean False if the scrolling should stop. */ function _scrollLabel() { // If the timeout is dead we return false. if (!isset($this->gtkTimeoutTag)) { return false; } // Get the visible text. $visible = $this->getVisibleText(); // Set the text. $this->label->set_text($visible); // We need to figure out which way to move the text. if ($this->direction == GTK_SCROLLINGLABEL_LEFT) { ++$this->currentCharPosition; } else { --$this->currentCharPosition; } // Check to see if we need to do change direction. if ($this->bounce) { // We are going to change direction eventually. if ($this->direction == GTK_SCROLLINGLABEL_LEFT && $visible == $this->labelText) { // If we are scrolling right to left and displaying the last character, // we need to turn around and move left to right next time. $this->setDirection(GTK_SCROLLINGLABEL_RIGHT); // We need to set the current position to the end. $this->currentCharPosition = strlen($this->padText()) - strlen($this->labelText); } elseif ($this->direction == GTK_SCROLLINGLABEL_RIGHT && $this->currentCharPosition <= 0) { // If we are scrolling left to right and we are showing the first // character, we need to turn around and go right to left next time. $this->setDirection(GTK_SCROLLINGLABEL_LEFT); // We need to start the scroll back at the begining. $this->currentCharPosition = 0; } } // Check to see if we need to start over. if ($this->direction == GTK_SCROLLINGLABEL_LEFT && $this->currentCharPosition >= strlen($this->padText())) { // We need to start back at the beginning. $this->currentCharPosition = 0; } elseif ($this->direction == GTK_SCROLLINGLABEL_RIGHT && $this->currentCharPosition < 0) { // We need to start back at the end. $this->currentCharPosition = strlen($this->labelText) + $this->visibleLength - 1; } return true; } /** * Begin scrolling the text from the start of the string. * Usually connected to an event. * * startScroll() will make the text begin scrolling in the * direction given by calling setDirection(). If the text * is scrolling left to right (GTK_SCROLLINGLABEL_RIGHT), the * current character position is set to the end of the text. * This means that the last character of the label will be * the first character shown. If the text is scrolling * right to left (GTK_SCROLLINGLABEL_LEFT), the current character * position is set to zero. This means that first character * shown will be a blank space. * * This method is best used when connected to an event. * * @access public * @param none * @return boolean true if the scrolling has started. * @uses unPause * @see setStartSignal */ function startScroll() { // First reset the current character position. $this->currentCharPosition = 0; // Then return the value of a call to the unpuase method. return $this->unPause(); } /** * Begin scrolling the text from the current character position. * Work horse for startScroll. Usually connected to an event. * * unPause() does pretty much the same thing as startScroll * except that it does not manipulate the current character * position. When you unpause the scroll, the text continues * from where it left off when it was paused. * * This method is best used when conneted to an event. * * @access public * @param none * @return boolean true if the scrolling has started. * @see setUnPauseSignal */ function unPause() { // Pretty much just like start but without resetting the postion. // First check to see if there is a timeout already started. if (isset($this->gtkTimeoutTag)) { // Throw error about scroll already started. $this->_error('Cannot unpause. Text not scrolling.', GTK_SCROLLINGLABEL_DEFAULT_ERROR, PEAR_ERROR_PRINT); return false; } elseif (!isset($this->speed)) { // Throw error about no value for speed. return $this->_error('Cannot unpause. No speed set.'); } else { // Start the scrolling. $this->gtkTimeoutTag =& gtk::timeout_add($this->speed, array(&$this, '_scrollLabel')); } // Give back the timeout tag. return $this->gtkTimeoutTag; } /** * Stop scrolling the text and return the string to the beginning. * Usually connected to an event. * * stopScroll will stop the text from scrolling and set the * current character position to zero. When the text is * started in motion again, it will be shown as it would if * it had been started for the first time. * * This method is best used when connected to an event. * * @access public * @param none * @return boolean true if the scrolling has stopped. * @uses pause * @see setStopSignal */ function stopScroll() { // First pause the scroll. if ($this->pause()) { // Then, if that worked, reset the current position. $this->currentCharPosition = 0; // Finally call the method to change the display returning // the value from that method to indicate success. return $this->_scrollLabel(); } return false; } /** * Stop the scroll where it is and do not change the current position. * Usually connected to an event. * * pause() will stop the text in its tracks. The scrolling * will stop but the visible text will not change. This is * different from stopScroll() in that stopScroll() will * clear the display back to its starting state. * * This method is best used when connected to an event. * * @access public * @param none * @return boolean true if the scrolling has stopped. * @see setPauseSignal */ function pause() { // Pretty much like stop but without reseting the position. if (empty ($this->gtkTimeoutTag)) { // Throw an error about no scroll in progress. $this->_error('Cannot pause. No timeout found.', GTK_SCROLLINGLABEL_DEFAULT_ERROR, PEAR_ERROR_PRINT); return false; } else { // All we need todo is unset the tag member because it is a reference. unset ($this->gtkTimeoutTag); // Indicate success by returning true. return true; } } /** * Connect a signal to a method. * * This private method will connect the event $signal to the * method $methodName. If the optional parameter $after is * set to true, the event will be connected using connect * after. All methods connected to an event with connect * after will be called after methods connected with plain * old connect. The GTK label does not listen for signals so * all events must be connected to the event box. * * @access private * @param object $signal The GTK_Signal to listen for. * @param string $methodName The method to connect. * @param boolean $after Should we make this one of the last calls. * @return boolean */ function _connectSignal($signal, $methodName, $after = false) { // Check that signal is accepted by eventbox. /** * @todo Check the above **/ // Check to see if we are using connect after if ($after) { $method = 'connect_after'; } else { $method = 'connect'; } // Connect the event box to the signal with the method. $this->widget->$method($signal, array(&$this, $methodName)); return true; } /** * Connect a signal to a method and act on another widget. * * This private method connects an event to a method and * passes that method a widget from which to get data or * to act on in some way. If the optional parameter $after * is set to true, the event will be connected using connect * after. All methods connected to an event with connect * after will be called after methods connected with plain * old connect. The GTK label does not listen for signals * so all events must be connected to the event box. * * @access private * @param object $signal The GTK_Signal to listen for. * @param string $methodName The method to connect. * @param &object $object The widget to act on. * @param boolean $after Should we make this one of the last calls. * @return boolean */ function _connectObjectSignal($signal, $methodName, &$object, $after = false) { // Check that signal is accepted by eventbox. /** * @todo Check the above **/ // Check to see if we are using connect after if ($after) { $method = 'connect_object_after'; } else { $method = 'connect_object'; } // Connect the event box to the signal with the method. $this->widget->$method($signal, array(&$this, $methodName), $object); } /** * Connect the pause method to an event. * * setPauseSignal() will make the event box listen for the * signal $signal and will envoke pause() when ever it is * heard. The signal should be a signal that GTKEventBox * listens for normally or a button press event. * * @access public * @param string $signal The GTK signal to connect to the method. * @return integer * @uses _connectSignal */ function setPauseSignal($signal) { // Call the private connectSignal method. return $this->_connectSignal($signal, 'pause'); } /** * Connect the unpause method to an event. * * setUnPauseSignal() will make the event box listen for the * signal $signal and will envoke unPause() when ever it is * heard. The signal should be a signal that GTKEventBox * listens for normally or a button press event. * * @access public * @param string $signal The GTK signal to connect to the method. * @return integer * @uses _connectSignal */ function setUnPauseSignal($signal) { // Call the private connectSignal method. return $this->_connectSignal($signal, 'unPause'); } /** * Connect the start method to an event. * * setStartSignal() will make the event box listen for the * signal $signal and will envoke startScroll() when ever it is * heard. The signal should be a signal that GTKEventBox * listens for normally or a button press event. * * * @access public * @param string $signal The GTK signal to connect to the method. * @return integer * @uses _connectSignal */ function setStartSignal($signal) { // Call the private connectSignal method. return $this->_connectSignal($signal, 'startScroll'); } /** * Connect the stop method to an event. * * setStopSignal() will make the event box listen for the * signal $signal and will envoke stopScroll() when ever it is * heard. The signal should be a signal that GTKEventBox * listens for normally or a button press event. * * * @access public * @param string $signal The GTK signal to connect to the method. * @return integer * @uses _connectSignal */ function setStopSignal($signal) { // Call the private connectSignal method. return $this->_connectSignal($signal, 'stopScroll'); } /** * Set the speed of the scrolling text. * * setSpeed() will change how quickly the text scrolls * across the visible label area. $speed is the number * of milliseconds to wait between calls to _scrollLabel. * $speed is passes to gtk::timeout_add(). If $restart * is set to true, the speed of the text will be changed * immediately. Otherwise the speed will not be changed * until _scrollLabel is called again. This effectively * means that the speed changes one letter after you set * the new speed if $restart is false. * * @access public * @param string $speed The speed the text should scroll. * @param boolean $restart Whether or not the speed should be changed before the next call to _scrollLabel * @return integer */ function setSpeed($speed, $restart = false) { // Check the speed. if (!is_numeric($speed) || $speed < 1 || $speed > 1000) { // Throw an error about illegal speed value $this->_error('Cannot set speed. Invalid value: ' . $speed, GTK_SCROLLINGLABEL_DEFAULT_ERROR, PEAR_ERROR_PRINT); } else { // Speed is the number of milliseconds between timeouts. $this->speed = $speed; } // If the scroll is currently moving we may need to // pause and unpause the scroll. if ($restart && isset ($this->gtkTimeoutTag)) { // Pausing and unpausing the scroll will affectively change the speed. $this->pause(); $this->unPause(); } return $this->speed; } /** * Set the diretion that the text should scroll. * * Set the direction that the text will move across the visible * area of the label. The only accepted directions are the two * constants GTK_SCROLLINGLABEL_LEFT and GTK_SCROLLINGLABEL_RIGHT which move the * from right to left and left to right respectively. The return * value is the diretion the text will move on the next call to * _scrollLabel(). * * @access public * @param integer $direction (GTK_SCROLLINGLABEL_LEFT|GTK_SCROLLINGLABEL_RIGHT) * @return integer */ function setDirection($direction) { // Check direction. if ($direction != GTK_SCROLLINGLABEL_LEFT && $direction != GTK_SCROLLINGLABEL_RIGHT) { // Throw an error about illegal direction choice. $this->_error('Cannot set direction. Illegal value: ' . $direction, GTK_SCROLLINGLABEL_DEFAULT_ERROR, PEAR_ERROR_PRINT); } else { $this->direction = $direction; } return $this->direction; } /** * Set whether or not the text should change directions when it hits an edge * * If bounce is true, the text will scroll to the left until the * first character hits the left edge of the visible window then * it will scroll to the right. When the last character hits the * right edge of the visible window the text will scroll back to * the left. * * Note: I don't know what will happen if bounce is true and the * text is larger than what can be viewed at one time in the * window. Therefore it is suggested that the length of the text * always be at least one less than the size of the window. * * @access public * @param boolean $bounce true means change directions. * @return boolean The current state of $this->bounce */ function setBounce($bounce) { $this->bounce = $bounce; return $this->bounce; } /** * Deprecated method to set bouncing. * * @deprecated * @access public * @param boolean $bounce true means change directions. * @return boolean The current state of $this->bounce * @see setBounce */ function bounce($bounce) { return $this->setBounce($bounce); } /** * Set the style in which the text will be displayed. * * setStyle() lets you define the look of the text that is * scrolling as well as the background of the widget. * * This method has not been implemented yet. * * @access public * @param &object $style The GTK_Style object to use. * @return &object */ function setStyle(&$style) { $this->label->set_style($style); } /** * Get the label's style widget. * * getStyle() returns the label's style widget. This lets you * make changes to the style to alter the look and feel of the * widget. You can change the font of the display, the color of * the background, etc. * * @access public * @param none * @return &object */ function &getStyle() { return $this->label->get_style(); } /** * Return the portion of the label text that should be visible * * getVisibleText() is used internally to get the text that * should be shown everytime the text scrolls. It can also * be called publically to get the text that is currently * displayed in the visible window area. The part of the text * that is visible depends on the current character position * and the direction the text is moving. * * @access public * @param none * @return string The visible text. * @uses padText() */ function getVisibleText() { // Pad the text. $text = $this->padText(); // We need to show from the current character position to // the character at currentCharPosition + visibleLength. if ($this->direction == GTK_SCROLLINGLABEL_LEFT) { $text = substr($text, $this->currentCharPosition, $this->visibleLength); } else { // I want to start at the end and get the text // $visibleLength in front of that. $text = substr($text, $this->currentCharPosition - $this->visibleLength, $this->visibleLength); } return $text; } /** * Pad the text with enough space to fill the visible area. * * padText adds the needed amount of white space to the * text so that it can scroll properly. When the text is * set to bounce the padding should only be what is needed * to make the string as long as the visible window area. * If the text is not bouncing, the text must be padded with * as many spaces as the length of the visible area. * * @access public * @param none * @return string The padded text. */ function padText() { // Get the full label text. $text = $this->labelText; // We need to pad the text on the left unless we are bouncing the text. if (!$this->bounce) { $text = str_pad($text, strlen($text) + $this->visibleLength, ' ', STR_PAD_LEFT); } elseif (strlen($this->labelText) < $this->visibleLength) { $text = str_pad($text, $this->visibleLength, ' ', STR_PAD_LEFT); } return $text; } /** * Return all of the text that can ever be shown by this label. * * @access public * @param none * @return string */ function getFullText() { return $this->labelText; } /** * Return all of the text that is not currently visible. * * @access public * @param none * @return string */ function getHiddenText() { // Pad the text. $text = $this->padText(); // We need to get the text minus the visible portion. // I don't know if this will ever be useful. $firstPart = substr($text, 0, $this->currentCharPosition); $secondPart = substr($text, $this->currentCharPosition + $this->visibleLength); return $firstPart . $secondPart; } /** * Set the full text of the label. * * setFullText() will change the text of the scrolling label. * The return value is what the text of the label will be * when _scrollLabel is next called. * * @access public * @param string $text The new text for the label. * @return string The label's text. */ function setFullText($text) { // Set the label text to the supplied text. $this->labelText = $text; return $this->labelText; } /** * Change the current character position. * * jumpToChar() allows you to go directly to a character * position on the next call to _scrollLabel. The new * position must be between zero (the first character) * and the length of the label minus one. The character * position should be calculated using the string from * padText(). When the text is scrolling to the left the * $charPosition should be the left-most character to * display. When text is scrolling to the right, * $charPosition should be the right-most character to * display. * * The visible label will not change until _scrollLabel * is called again. * * @access public * @param integer $charPosition Depending on the direction either the left or right most character to display. * @return integer The new current character position. (PEAR_Error when there is a problem.) */ function jumpToChar($charPosition) { // Check that the charPosition exists. if (!is_numeric ($charPosition) || $charPosition < 0 || $charPosition >= strlen($this->labelText)) { // Throw an error about illegal char position. $this->_error('Cannot jump to character. Invalid value. Character position must be a number between zero and the length of the string (' . strlen($this->padText()) . ')'); } else { // Set the current character position. $this->currentCharPosition = $charPosition; } return $this->currentCharPosition; } /** * Change how many characters should be visible at any given time. * * setVisibleLength() will set the number of characters that are * visible at any given time. While it is ik to set the visible * length smaller than the width of the displaying widget, you * probably don't want to make it larger then the width of the * displaying widget. It will make the padded lenght longer and * add additional time before the text begins to appear on screen. * * @access public * @param integer $length The new size of the visible area in characters. * @return integer The new size of the visible area in characters. */ function setVisibleLength($length) { // First check the length. if (!is_numeric($length) || $length < 0) { // Throw an error about illegal visible length. $this->_error('Cannot set visible length. Invalid value. Length must be a number greater than zero.'); } else { $this->visibleLength = $length; } return $this->visibleLength; } /** * Return the visible area length in characters * * @access public * @param none * @return integer */ function getVisibleLength() { return $this->visibleLength; } /** * Show the GTK components. * * @access public * @param none * @return void */ function show() { // Show the eventbox and the label. $this->widget->show_all(); } /** * Hide the GTK components. * * @access public * @param none * @return void */ function hide() { // Hide the label and the eventbox. $this->widget->hide_all(); } /** * Return the GTKEventBox with the GTKLabel inside. * * @access public * @param none * @return &object */ function &getScrollingLabel() { return $this->widget; } /** * Raise a pear error. * * _error will raise a PEAR error with $msg as the message. * If the optional parameter $code is set, that error code * will be used. Otherwise the default error code will be * used. If the optional $pearMode is passed that mode will * be used to display/return the error. * * @access private * @param string $msg The human readable error message. * @param integer $code The error code. * @param integer $pearMode The PEAR mode for the error. * @return mixed A PEAR_Error or void. */ function _error($msg, $code = GTK_SCROLLINGLABEL_DEFAULT_ERROR, $pearMode = PEAR_ERROR_RETURN) { // Require the pear class so that we can use its error functionality. require_once ('PEAR.php'); // Check whether or not we should print the error. if ($pearMode == PEAR_ERROR_PRINT) { PEAR::setErrorHandling(PEAR_ERROR_PRINT, "Gtk_ScrollingLabel error: %s<BR />\n"); } PEAR::raiseError($msg, $code, $pearMode); } } /* * Local variables: * tab-width: 4 * c-basic-offset: 4 * End: */ ?> 
