Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 749 lines (690 sloc) 21.707 kb
f6b0e85 Initial check in of Gtk_Styled package.
Scott Mattocks authored
1 <?php
2 /* vim: set expandtab tabstop=4 shiftwidth=4: */
3 // +----------------------------------------------------------------------+
4 // | PHP Version 4 |
5 // +----------------------------------------------------------------------+
6d51367 DocBlock and header comment fixes.
Scott Mattocks authored
6 // | Copyright (c) 2005 Scott Mattocks |
f6b0e85 Initial check in of Gtk_Styled package.
Scott Mattocks authored
7 // +----------------------------------------------------------------------+
8 // | This source file is subject to version 3.0 of the PHP license, |
9 // | that is bundled with this package in the file LICENSE, and is |
10 // | available through the world-wide-web at the following url: |
11 // | http://www.php.net/license/3_0.txt. |
12 // | If you did not receive a copy of the PHP license and are unable to |
13 // | obtain it through the world-wide-web, please send a note to |
14 // | license@php.net so we can mail you a copy immediately. |
15 // +----------------------------------------------------------------------+
16 // | Author: Scott Mattocks <scottmattocks@php.net> |
17 // +----------------------------------------------------------------------+
18 //
19 // $Id$
20
21 // Define the error code if it isn't already.
22 if (!defined('GTK_STYLED_ERROR')) {
23 define('GTK_STYLED_ERROR', 1);
24 }
25
26 /**
27 * A styleable adjustment pseudo widget.
28 *
29 * The interface for this should mimic a GtkAdjustment.
30 *
31 * @abstract
32 * @author Scott Mattocks <scottmattocks@php.net>
33 * @version @VER@
34 * @category Gtk
6d51367 DocBlock and header comment fixes.
Scott Mattocks authored
35 * @package Gtk_Styled
f6b0e85 Initial check in of Gtk_Styled package.
Scott Mattocks authored
36 * @subpackage Adjustment
37 * @license PHP version 3.0
6d51367 DocBlock and header comment fixes.
Scott Mattocks authored
38 * @copyright Copyright &copy; 2005 Scott Mattocks
f6b0e85 Initial check in of Gtk_Styled package.
Scott Mattocks authored
39 */
40 class Gtk_Styled_Adjustment {
41
42 /**
43 * The useable widget
44 * @var object
45 */
46 var $widget;
47 /**
48 * The track that the bar sits in.
49 * @var object
50 */
51 var $track;
52 /**
53 * The portion of the track before the bar.
54 * @var object
55 */
56 var $preTrack;
57 /**
58 * The visual representation of the adjustment.
59 * @var object
60 */
61 var $bar;
62 /**
63 * The portion of the track after the bar.
64 * @var object
65 */
66 var $postTrack;
67
68 /**
69 * The value that the adjustment represents.
70 * @var double
71 */
72 var $value;
73 /**
74 * The lower limit of the value.
75 * @var double
76 */
77 var $lower;
78 /**
79 * The upper limit of the value.
80 * @var double
81 */
82 var $upper;
83 /**
84 * The amount that the value should change with one step.
85 * @var double
86 */
87 var $stepIncrement;
88 /**
89 * The amount that the value should change with one page.
90 * @var double
91 */
92 var $pageIncrement;
93 /**
94 * The size of one page's worth of data.
95 * @var double
96 */
97 var $pageSize;
98 /**
99 * The widget width/height (depending on the orientation)
100 * @var integer
101 */
102 var $width = 15;
103
104 /**
105 * Constructor.
106 *
107 * The constructor should set the basic properties of the pseudo
108 * widget and then create the more advanced properties. The advanced
109 * properties include the bar and the track that it moves in.
110 *
111 * @access public
112 * @param double $value
113 * @param double $lower
114 * @param double $upper
115 * @param double $step_inc
116 * @param double $page_inc
117 * @param double $page_size
118 * @return void
119 */
120 function Gtk_Styled_Adjustment($value, $lower, $upper,
121 $step_inc, $page_inc, $page_size)
122 {
123 // Check the passed values.
124 if (!is_numeric($value)) {
125 return $this->_handleError('Gtk_Styled_Adjustment::value is expected to be a number.');
126 } else {
127 $this->value = $value;
128 }
129 if (!is_numeric($lower)) {
130 return $this->_handleError('Gtk_Styled_Adjustment::lower is expected to be a number.');
131 } else {
132 $this->lower = $lower;
133 }
134 if (!is_numeric($upper)) {
135 return $this->_handleError('Gtk_Styled_Adjustment::upper is expected to be a number.');
136 } else {
137 $this->upper = $upper;
138 }
139 if (!is_numeric($step_inc)) {
140 return $this->_handleError('Gtk_Styled_Adjustment::stepIncrement is expected to be a number.');
141 } else {
142 $this->stepIncrement = $step_inc;
143 }
144 if (!is_numeric($page_inc)) {
145 return $this->_handleError('Gtk_Styled_Adjustment::page increment is expected to be a number.');
146 } else {
147 $this->pageIncrement = $page_inc;
148 }
149 if (!is_numeric($page_size)) {
150 return $this->_handleError('Gtk_Styled_Adjustment::pageSize is expected to be a number.');
151 } else {
152 $this->pageSize = $page_size;
153 }
154
155 // Create the track and the bar.
156 $this->_createTrack();
157 }
158
159 /**
160 * Get the final product that the user can use.
161 *
162 * To make things easier for the user, and to keep some
163 * consistency with other PEAR Gtk classes, the final usable
164 * object is called widget and is returned from the getWidget
165 * method.
166 *
167 * @access public
168 * @param none
169 * @return &object
170 */
171 function &getWidget()
172 {
173 return $this->widget;
174 }
175
176 /**
177 * Get the container that will hold the adjustment track.
178 *
179 * The properties of the track container determin the direction
180 * that the adjustment will be shown. The possible options are
181 * GtkVBox or GtkHBox producing a vertical or horizontal adjustment
182 * respectively.
183 *
184 * @abstract
185 * @access private
186 * @param none
187 * @return widget The container may not be a child of GtkBin.
188 */
189 function &_getTrackContainer()
190 {
191 // Abstract.
192 $this->_handleError('Gtk_Styled_Adjustment is an abstract class and ' .
193 'should not be instantiated directly. Use ' .
194 'Gtk_HStyleAdjustment or Gtk_VStyleAdjustment ' .
195 'instead.');
196 }
197
198 /**
199 * Create the track that the bar will live in.
200 *
201 * The track acts as the boundry for the bar. It contains the
202 * widget and sets a limit on the values that the bar may
203 * represent. The properties of the bar may be influenced by
204 * the properties of the track.
205 *
206 * Depending on the type of widget that uses the adjustment, the
207 * bar may not have to move with in the track but just grow and
208 * shrink within it. (ProgressBar) The track acts as a boundry for
209 * the bar no matter how it is used.
210 *
211 * @access private
212 * @param none
213 * @return void
214 */
215 function _createTrack()
216 {
217 // ALL THIS MOVEMENT BELONGS IN THE SCROLL BAR!!!
218 // It is left here for demonstration purposes only.
219
220 // Create the track that the bar will live in.
221 $this->track =& $this->_getTrackContainer();
222 $this->_setTrackSize();
223
224 // Create an event box to represent the empty space to the left.
225 $this->preTrack =& new GtkEventBox;
226 $this->preTrack->set_usize($this->value, -1);
227
228 // Create an event box to represnet the empty space to the right.
229 $this->postTrack =& new GtkEventBox;
230
231 // Add everything to the track.
232 $this->track->pack_start($this->preTrack, false, false, 0);
233 $this->track->pack_start($this->_createBar(), false, false, 0);
234 $this->track->pack_start($this->postTrack, true, true, 0);
235
236 // Add the track to the widget.
237 $this->widget =& new GtkHBox();
238 $this->widget->pack_start($this->track, true, true, 0);
239
240 // Set the sizes.
241 $this->_setBarSize();
242 $this->_setTrackSize();
243 $this->_setBarPosition();
244 }
245
246 /**
247 * Create the bar that visually represents the adjustment.
248 *
249 * The bar that lives within the track is capable of chaning size
250 * and position based on the values that the track represents.
251 *
252 * @access private
253 * @param none
254 * @return &$object
255 */
256 function &_createBar()
257 {
258 $this->bar =& new GtkButton(NULL);
259 $this->_setBarSize();
260
261 return $this->bar;
262 }
263
264 /**
265 * Set the size of the bar.
266 *
267 * The bar size is configurable. Depending on how the adjustment is
268 * used, the bar size may depend entirely on its value or it may
269 * change with respect to its environment. If the adjustment is used
270 * as a progress bar, the size of the bar is directly related to the
271 * percentage of the task that is complete. If the adjustment is used
272 * as a scroll bar, the size of the bar is related to the amount of
273 * the scrolling widget that is currently shown compared to its total
274 * size.
275 *
276 * @abstract
277 * @access private
278 * @param none
279 * @return void
280 */
281 function _setBarSize()
282 {
283 // Abstract.
284 $this->_handleError('Gtk_Styled_Adjustment is an abstract class and ' .
285 'should not be instantiated directly. Use ' .
286 'Gtk_HStyleAdjustment or Gtk_VStyleAdjustment ' .
287 'instead.');
288 }
289
290 /**
291 * Set the bars position within the track.
292 *
293 * Set the starting position of the bar with in the track. The bar
294 * cannot start (length of track) - (length of bar). The position
295 * of the bar is mostly only relavent when the adjustment is being
296 * used as a scroll bar or when being used as an activity progress
297 * indicator.
298 *
299 * The bar position is determined by the width/height of the event
300 * box that preceeds the bar.
301 *
302 * @abstract
303 * @access private
304 * @param none
305 * @return void
306 */
307 function _setBarPosition()
308 {
309 // Abstract
310 $this->_handleError('Gtk_Styled_Adjustment is an abstract class and ' .
311 'should not be instantiated directly. Use ' .
312 'Gtk_HStyleAdjustment or Gtk_VStyleAdjustment ' .
313 'instead.');
314 }
315
316 /**
317 * Set the size of the entire track.
318 *
319 * Sets the size of the entire track. The track contains the preTrack
320 * the bar and the postTrack.
321 *
322 * This method is abstract and should be overwritten in the child
323 * classes
324 *
325 * @abstract
326 * @access private
327 * @param none
328 * @return void
329 */
330 function _setTrackSize()
331 {
332 // Abstract.
333 $this->_handleError('Gtk_Styled_Adjustment is an abstract class and ' .
334 'should not be instantiated directly. Use ' .
335 'Gtk_HStyleAdjustment or Gtk_VStyleAdjustment ' .
336 'instead.');
337 }
338
339 /**
340 * Set the current adjustment value.
341 *
342 * Sets the value that the adjustment represents. The value has an
343 * impact on the bar position and size.
344 *
345 * @access public
346 * @param double $value The new adjustment value.
347 * @return void
348 */
349 function setValue($value)
350 {
351 // Check to see if the widget has been realized first.
352 $this->_checkRealized();
353
354 // Set the new value
355 $this->value = $value;
356
357 // Don't let the value exceed the bounds.
358 if ($this->value > $this->upper - $this->pageSize) {
359 $this->value = $this->upper - $this->pageSize;
360 }
361 if ($this->value < $this->lower) {
362 $this->value = $this->lower;
363 }
364
365 // Set the bar position.
366 $this->_setBarPosition();
367
368 return $this->value;
369 }
370
371 /**
372 * Set the lower limit of the adjustment.
373 *
374 * Sets the lower limit of the adjustment widget. The lower limit
375 * affects the bar size and position.
376 *
377 * @access public
378 * @param double $lower The new lower limit value.
379 * @return void
380 */
381 function setLower($lower)
382 {
383 // Check to see if the widget has been realized first.
384 $this->_checkRealized();
385
386 if (!is_numeric($lower)) {
387 return $this->_handleError('Lower expects a numeric value.');
388 }
389
390 $this->lower = $lower;
391 $this->_setBarSize();
392 $this->_setBarPosition();
393 }
394
395 /**
396 * Set the upper limit of the adjustment.
397 *
398 * Sets the upper limit of the adjustment widget. The upper limit
399 * affects the bar size and position.
400 *
401 * @access public
402 * @param double $upper The new upper limit value.
403 * @return void
404 */
405 function setUpper($upper)
406 {
407 // Check to see if the widget has been realized first.
408 $this->_checkRealized();
409
410 if (!is_numeric($upper)) {
411 return $this->_handleError('Upper expects a numeric value.');
412 }
413
414 $this->upper = $upper;
415
416 $this->_setBarSize();
417 $this->_setBarPosition();
418 }
419
420 /**
421 * Set the size of one step.
422 *
423 * Sets the size of one step. One step is the amount a scroll bar
424 * will move when the arrow at the begining or end of the scroll
425 * bar is pressed.
426 *
427 * @access public
428 * @param double $increment The new size of one step
429 * @return void
430 */
431 function setStepIncrement($increment)
432 {
433 // Check to see if the widget has been realized first.
434 $this->_checkRealized();
435
436 if (!is_numeric($increment)) {
437 return $this->_handleError('Step increment expects a numeric value.');
438 }
439
440 $this->stepIncrement = $increment;
441 }
442
443 /**
444 * Set the size of one page movement.
445 *
446 * Sets the size of one page. One page is the amount a scroll bar
447 * will move when the space around the bar of a scroll bar is
448 * pressed.
449 *
450 * @access public
451 * @param double $increment The new size of one page
452 * @return void
453 */
454 function setPageIncrement($increment)
455 {
456 // Check to see if the widget has been realized first.
457 $this->_checkRealized();
458
459 if (!is_numeric($increment)) {
460 return $this->_handleError('Page increment expects a numeric value.');
461 }
462
463 $this->pageIncrement = $increment;
464 }
465
466 /**
467 * Set the size of one page.
468 *
469 * Sets the size of one page. One page is the size of the display
470 * area. Changing the page size has an affect on the bar size and
471 * position.
472 *
473 * @access public
474 * @param double $increment The new size of one page
475 * @return void
476 */
477 function setPageSize($pageSize)
478 {
479 // Check to see if the widget has been realized first.
480 $this->_checkRealized();
481
482 if (!is_numeric($pageSize)) {
483 return $this->_handleError('Page size expects a numeric value.');
484 }
485
486 $this->pageSize = $pageSize;
487 $this->_setBarSize();
488 $this->_setBarPosition();
489 }
490
491 /**
492 * Notify the system that a change has been made.
493 *
494 * @access public
495 * @param none
496 * @return void
497 */
498 function changed()
499 {
500 // Empty
501 }
502
503 /**
504 * Notify the system that a value has changed.
505 *
506 * @access public
507 * @param none
508 * @return void
509 */
510 function value_changed()
511 {
512 // Empty.
513 }
514
515 /**
516 * Prevent the bound of the track from being exceeded by the bar.
517 *
518 * @access public
519 * @param double $lower The lower boundry.
520 * @param double $upper The upper boundry.
521 * @return void
522 */
523 function clamp_page($lower, $upper)
524 {
525 // Empty.
526 }
527
528 /**
529 * Alias of setValue. Added for API consistency.
530 *
531 * @see setValue
532 */
533 function set_value($value)
534 {
535 $this->setValue($value);
536 }
537
538 /**
539 * Set the style for a portion of the adjustment.
540 *
541 * Each portion of the adjustment is styleable. The style that
542 * is passed will be applied to the portion of the adjustment.
543 *
544 * @access public
545 * @param string $portion The portion to style.
546 * @param widget &$style The style to apply.
547 * @return void
548 */
549 function setStyle($portion, $style)
550 {
551 // Check for the portion.
552 if (!isset($this->$portion)) {
553 $this->_handleError('Undefined portion: ' . $portion . ' Cannot apply style.');
554 }
555 $this->$portion->set_style($style);
556 }
557
558 /**
559 * Set the pix mask for the bar.
560 *
561 * Make the bar appear to be something other than a rectangle.
562 * This lets you create images for the bar so that it can be
563 * anything you want. This is the ultimate in adjustment
564 * customizatioin.
565 *
566 * NOTE: I don't know what will happen if you change the size
567 * of the bar when a mask is applied. Changing the page size
568 * and upper and lower values could have undesired effects.
569 *
570 * @access public
571 * @param object &$mask The image to make the bar appear as.
572 * @return void
573 */
574 function setBarMask(&$mask, $x = 0, $y = 0)
575 {
576 $this->bar->shape_combine_mask($mask, $x, $y);
577 }
578
579 /**
580 * Set the contents of the bar to the given widget.
581 *
582 * This method makes it possible to put a label, pixmap, or
583 * any other widget into the bar in order to alter the bar's
584 * appearance. When combined with setBarMask(), this method
585 * makes the style an shape of the adjustment bar completely
586 * controllable by the programmer.
587 *
588 * The previous contents of the bar are returned after the
589 * new contents have been added.
590 *
591 * @access public
592 * @param object &$widget The new widget to put in the bar.
593 * @return widget The previous contents of the bar.
594 */
595 function &setBarContents(&$widget)
596 {
597 $prevChild = $this->bar->child;
598 $this->bar->remove($prevChild);
599 $this->bar->add($widget);
600
601 return $prevChild;
602 }
603
604 /**
605 * Get the adjustments value.
606 *
607 * @access public
608 * @param none
609 * @return double
610 */
611 function getValue()
612 {
613 return $this->value;
614 }
615
616 /**
617 * Get the adjustments lower limit.
618 *
619 * @access public
620 * @param none
621 * @return double
622 */
623 function getLower()
624 {
625 return $this->lower;
626 }
627
628 /**
629 * Get the adjustments upper limit.
630 *
631 * @access public
632 * @param none
633 * @return double
634 */
635 function getUpper()
636 {
637 return $this->upper;
638 }
639
640 /**
641 * Get the adjustments step increment.
642 *
643 * @access public
644 * @param none
645 * @return double
646 */
647 function getStepIncrement()
648 {
649 return $this->stepIncrement;
650 }
651
652 /**
653 * Get the adjustments page increment.
654 *
655 * @access public
656 * @param none
657 * @return double
658 */
659 function getPageIncrement()
660 {
661 return $this->pageIncrement;
662 }
663
664 /**
665 * Get the adjustments page size.
666 *
667 * @access public
668 * @param none
669 * @return double
670 */
671 function getPageSize()
672 {
673 return $this->pageSize;
674 }
675
676 /**
677 * Check to see that the mouse is within the boundries of the
678 * bar.
679 *
680 * Check the current mouse position to see if it is within
681 * the bounds of the adjustment bar. It is only necessary to
682 * check if the mouse is with in one direction of the bar's
683 * alloted space. For example, we only care if the mouse is
684 * within the y-range of a vertical adjustment.
685 *
686 * @abstract
687 * @access public
688 * @param none
689 * @return boolean
690 */
691 function checkMouseBounds()
692 {
693 // Abstract.
694 $this->_handleError('Gtk_Styled_Adjustment is an abstract class and ' .
695 'should not be instantiated directly. Use ' .
696 'Gtk_HStyleAdjustment or Gtk_VStyleAdjustment ' .
697 'instead.');
698 }
699
700 /**
701 * Checks to make sure that the widgets have been realized.
702 *
703 * Many of the classes that use Gtk_Styled_Adjustment objects
704 * expect that the widgets have been realized. This is
705 * becuase they use properties which are only set after
706 * object realization.
707 *
708 * @access private
709 * @param none
710 * @return boolean true if realized, false if not
711 */
712 function _checkRealized()
713 {
714 if (!isset($this->widget->window)) {
715 $this->_handleError('Setting values on a Gtk_Styled_Adjustment ' .
716 'that has not yet been realized can have ' .
717 'unexpected results.');
718 return false;
719 } else {
720 return true;
721 }
722 }
723
724 /**
725 * Error handling method.
726 *
727 * Errors should be handled with PEAR::Error_Stack
728 *
729 * @access private
730 * @param string $message
731 * @param integer $level
732 * @return mixed
733 */
734 function _handleError($msg, $code = GTK_STYLED_ERROR, $pearMode = PEAR_ERROR_PRINT)
735 {
736 // Require the pear class so that we can use its error functionality.
737 require_once ('PEAR.php');
738
739 // Check whether or not we should print the error.
740 PEAR::raiseError($msg, $code, $pearMode);
741 }
742 }
743 /*
744 * Local variables:
745 * tab-width: 4
746 * c-basic-offset: 4
747 * End:
748 */
749 ?>
Something went wrong with that request. Please try again.