Gnome User Interface Library Reference Manual
<<< Previous PageHomeUpNext Page >>>

GtkClock

Name

GtkClock -- A small text clock widget, capable of realtime, count-up and count-down modes

Synopsis


#include <gnome.h>


struct      GtkClock;
enum        GtkClockType;
GtkWidget*  gtk_clock_new                   (GtkClockType type);
void        gtk_clock_set_format            (GtkClock *gclock,
                                             gchar *fmt);
void        gtk_clock_set_seconds           (GtkClock *gclock,
                                             time_t seconds);
void        gtk_clock_set_update_interval   (GtkClock *gclock,
                                             gint seconds);
void        gtk_clock_start                 (GtkClock *gclock);
void        gtk_clock_stop                  (GtkClock *gclock);

Object Hierarchy


  GtkObject
   +----GtkWidget
         +----GtkMisc
               +----GtkLabel
                     +----GtkClock

Description

The GtkClock widget provides an easy way of providing a textual clock in your application. It supports realtime display, as well as count up and count down modes. The clock widget could conceivably be used in such applications as an application's status bar, or as the basis for a panel applet, etc.

Three modes of operation are supported. These are realtime - which displays the current time, count-up/increasing - which counts up from an initial value (like a stopwatch), and count-down/decreasing - which counts down from an initial value.

Note, however, that the accuracy of the gtkclock widget is limited to 1 second.

Details

struct GtkClock

struct GtkClock;

You should not access the members of the GtkClock struct directly, instead, access them through the gtk_clock_* functions.

enum GtkClockType

typedef enum
{
	GTK_CLOCK_INCREASING,
	GTK_CLOCK_DECREASING,
	GTK_CLOCK_REALTIME
} GtkClockType;

Three modes are supported - realtime (GTK_CLOCK_REALTIME), count-up (GTK_CLOCK_INCREASING) and count-down (GTK_CLOCK_DECREASING). In realtime mode, the widget displays the current local machine time. In count-up mode, the widget counts up either from an initial value (as specified with gtk_clock_set_seconds) or from the default of 0 seconds. In count-down mode, the widget counts down from a specified value or 0 seconds. Note that negative times are possible, and that the clock does not stop at 0 seconds in count down mode.

gtk_clock_new ()

GtkWidget*  gtk_clock_new                   (GtkClockType type);

Creates a new GtkClock widget.

type :A GtkClockType value, specifying what mode this widget is to display in. There are three options: GTK_CLOCK_INCREASING, GTK_CLOCK_DECREASING, GTK_CLOCK_REALTIME. These options are described above.
Returns :GtkWidget * on success, NULL on failure.

gtk_clock_set_format ()

void        gtk_clock_set_format            (GtkClock *gclock,
                                             gchar *fmt);

Set the format of a GtkClock widget. The syntax of the format string is identical to that of the function strftime(3). Further information about time format strings can be found on this man page. The widget defaults to a format string of "%H:%M" in realtime mode, or "%H:%M:%S" in count-up or count-down modes.

gclock :A pointer to a GtkClock widget.
fmt :A time format string, as described by the man page strftime(3).

gtk_clock_set_seconds ()

void        gtk_clock_set_seconds           (GtkClock *gclock,
                                             time_t seconds);

Set the current time as displayed by the clock in count-up and count-down modes. This function has no effect in realtime mode, as the clock time is determined by the system clock in realtime mode.

gclock :A pointer to a GtkClock widget.
seconds :The time to display on the clock, measured in seconds.

gtk_clock_set_update_interval ()

void        gtk_clock_set_update_interval   (GtkClock *gclock,
                                             gint seconds);

Set the interval at which the GtkClock widget is updated. The seconds parameter is used to determine how often the time shown on the widget is updated. The default value is to update every second, but you may wish to increase this value. If you set the update interval to 0, the clock is never updated.

gclock :A pointer to a GtkClock widget.
seconds :The interval at which to update the clock widget, measured in seconds.

gtk_clock_start ()

void        gtk_clock_start                 (GtkClock *gclock);

Start the clock counting in count-up or count-down modes. The clock will begin counting up or down from the time when this function is called, until gtk_clock_stop is called. This function has no effect in the realtime mode (you can't start and stop real time! :-).

gclock :A pointer to a GtkClock widget.

gtk_clock_stop ()

void        gtk_clock_stop                  (GtkClock *gclock);

Stop the clock counting in count-up or count-down modes. The clock ceases counting up or down, and the last time reached remains on the display. This function has no effect in the realtime mode (you can't start and stop real time! :-).

gclock :A pointer to a GtkClock widget.



<<< Previous PageHomeUpNext Page >>>
GnomeStockGtkTed