From: GMT 1998 Tony Gale Date: Mon, 16 Mar 1998 09:25:13 +0000 (+0000) Subject: - New subsection on colourselection from Tom Bech - Moved X-Git-Url: http://pileus.org/git/?a=commitdiff_plain;h=60c008eb99a7bf27319c2b66dcf2ca5315bb57ec;p=~andy%2Fgtk - New subsection on colourselection from Tom Bech - Moved Mon Mar 16 09:15:03 GMT 1998 Tony Gale * docs/gtk_tut.sgml: - New subsection on colourselection from Tom Bech - Moved fileselection text to Miscallaneous Widgets section - Started new section on the Text widget - Removed Viewport, Paned, HPaned and VPaned from list of NO_WINDOW widgets. --- diff --git a/ChangeLog b/ChangeLog index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 83c8fc09d..90f2d7629 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,12 @@ +Mon Mar 16 09:15:03 GMT 1998 Tony Gale + + * docs/gtk_tut.sgml: + - New subsection on colourselection from Tom Bech + - Moved fileselection text to Miscallaneous Widgets section + - Started new section on the Text widget + - Removed Viewport, Paned, HPaned and VPaned from list of + NO_WINDOW widgets. + Mon Mar 16 01:33:36 1998 Owen Taylor * gtk-config.in: Added trailing newline, hopefully will diff --git a/docs/gtk_tut.sgml b/docs/gtk_tut.sgml index fc85b6c9b..331e05e11 100644 --- a/docs/gtk_tut.sgml +++ b/docs/gtk_tut.sgml @@ -1552,16 +1552,12 @@ GtkBox GtkImage GtkItem GtkLabel -GtkPaned GtkPixmap GtkScrolledWindow GtkSeparator GtkTable -GtkViewport GtkAspectFrame GtkFrame -GtkVPaned -GtkHPaned GtkVBox GtkHBox GtkVSeparator @@ -3015,15 +3011,6 @@ GtkWidget* gtk_entry_new_with_max_length (guint16 max); The first just creates a new Entry widget, whilst the second creates a new Entry and sets a limit on the length of the text within the Entry.. -The maximum length of the text within an entry widget may be changed by a call to the following -function. If the current text is longer than this maximum, then it is upto us to alter the Entries -contents appropriately. - - -void gtk_entry_set_max_length (GtkEntry *entry, - guint16 max); - - There are several functions for altering the text which is currently within the Entry widget. void gtk_entry_set_text (GtkEntry *entry, @@ -3176,6 +3163,327 @@ int main (int argc, char *argv[]) } + + Color Selection +

+The color selection widget is, not surprisingly, a widget for interactive +selection of colors. This composite widget lets the user select a color by manipulating +RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done +either by adjusting single values with sliders or entries, or by picking the desired +color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also +be set. + +The color selection widget currently emits only one signal, "color_changed", which is emitted +whenever the current color in the widget changes, either when the user changes it or if +it's set explicitly through gtk_color_selection_set_color(). + +Lets have a look at what the color selection widget has to offer us. The widget comes +in two flavours; gtk_color_selection and gtk_color_selection_dialog: + + +GtkWidget *gtk_color_selection_new(void); + + +You'll probably not be using this constructor directly. It creates an orphan +GtkColorSelection widget which you'll have to parent yourself. The GtkColorSelection widget +inherits from the GtkVBox widget. + + +GtkWidget *gtk_color_selection_dialog_new(const gchar *title); + + +This is the most common color selection constructor. It creates a GtkColorSelectionDialog, which +inherits from a GtkDialog. It consists of a GtkFrame containing a GtkColorSelection widget, a +GtkHSeparator and a GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these +buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the +GtkColorSelectionDialog structure, (i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button). + + +void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel, + GtkUpdateType policy); + + +This function sets the update policy. The default policy is GTK_UPDATE_CONTINOUS which means that +the current color is updated continously when the user drags the sliders or presses the mouse and drags +in the hue-saturation wheel or value bar. If you experience performance problems, you may +want to set the policy to GTK_UPDATE_DISCONTINOUS or GTK_UPDATE_DELAYED. + + +void gtk_color_selection_set_opacity(GtkColorSelection *colorsel, + gint use_opacity); + + +The color selection widget supports adjusting the opacity of a color (also known as the alpha channel). +This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity. +Likewise, use_opacity set to FALSE will disable opacity. + + +void gtk_color_selection_set_color(GtkColorSelection *colorsel, + gdouble *color); + + +You can set the current color explicitly by calling this function with a pointer to an array +of colors (gdouble). The length of the array depends on whether opacity is enabled or not. +Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if +opacity is enabled, see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0. + + +void gtk_color_selection_get_color(GtkColorSelection *colorsel, + gdouble *color); + + +When you need to query the current color, typically when you've received a "color_changed" signal, +you use this function. Color is a pointer to the array of colors to fill in. See the +gtk_color_selection_set_color() function for the description of this array. + + + +Here's a simple example demonstrating the use of the GtkColorSelectionDialog. The program displays a window +containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the +color selection dialog changes the background color. + + +#include +#include +#include + +GtkWidget *colorseldlg = NULL; +GtkWidget *drawingarea = NULL; + +/* Color changed handler */ + +void color_changed_cb (GtkWidget *widget, GtkColorSelection *colorsel) +{ + gdouble color[3]; + GdkColor gdk_color; + GdkColormap *colormap; + + /* Get drawingarea colormap */ + + colormap = gdk_window_get_colormap (drawingarea->window); + + /* Get current color */ + + gtk_color_selection_get_color (colorsel,color); + + /* Fit to a unsigned 16 bit integer (0..65535) and insert into the GdkColor structure */ + + gdk_color.red = (guint16)(color[0]*65535.0); + gdk_color.green = (guint16)(color[1]*65535.0); + gdk_color.blue = (guint16)(color[2]*65535.0); + + /* Allocate color */ + + gdk_color_alloc (colormap, &gdk_color); + + /* Set window background color */ + + gdk_window_set_background (drawingarea->window, &gdk_color); + + /* Clear window */ + + gdk_window_clear (drawingarea->window); +} + +/* Drawingarea event handler */ + +gint area_event (GtkWidget *widget, GdkEvent *event, gpointer client_data) +{ + gint handled = FALSE; + GtkWidget *colorsel; + + /* Check if we've received a button pressed event */ + + if (event->type == GDK_BUTTON_PRESS && colorseldlg == NULL) + { + /* Yes, we have an event and there's no colorseldlg yet! */ + + handled = TRUE; + + /* Create color selection dialog */ + + colorseldlg = gtk_color_selection_dialog_new("Select background color"); + + /* Get the GtkColorSelection widget */ + + colorsel = GTK_COLOR_SELECTION_DIALOG(colorseldlg)->colorsel; + + /* Connect to the "color_changed" signal, set the client-data to the colorsel widget */ + + gtk_signal_connect(GTK_OBJECT(colorsel), "color_changed", + (GtkSignalFunc)color_changed_cb, (gpointer)colorsel); + + /* Show the dialog */ + + gtk_widget_show(colorseldlg); + } + + return handled; +} + +/* Close down and exit handler */ + +void destroy_window (GtkWidget *widget, gpointer client_data) +{ + gtk_main_quit (); +} + +/* Main */ + +gint main (gint argc, gchar *argv[]) +{ + GtkWidget *window; + + /* Initialize the toolkit, remove gtk-related commandline stuff */ + + gtk_init (&argc,&argv); + + /* Create toplevel window, set title and policies */ + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_window_set_title (GTK_WINDOW(window), "Color selection test"); + gtk_window_set_policy (GTK_WINDOW(window), TRUE, TRUE, TRUE); + + /* Attach to the "delete" and "destroy" events so we can exit */ + + gtk_signal_connect (GTK_OBJECT(window), "delete_event", + (GtkSignalFunc)destroy_window, (gpointer)window); + + gtk_signal_connect (GTK_OBJECT(window), "destroy", + (GtkSignalFunc)destroy_window, (gpointer)window); + + /* Create drawingarea, set size and catch button events */ + + drawingarea = gtk_drawing_area_new (); + + gtk_drawing_area_size (GTK_DRAWING_AREA(drawingarea), 200, 200); + + gtk_widget_set_events (drawingarea, GDK_BUTTON_PRESS_MASK); + + gtk_signal_connect (GTK_OBJECT(drawingarea), "event", + (GtkSignalFunc)area_event, (gpointer)drawingarea); + + /* Add drawingarea to window, then show them both */ + + gtk_container_add (GTK_CONTAINER(window), drawingarea); + + gtk_widget_show (drawingarea); + gtk_widget_show (window); + + /* Enter the gtk main loop (this never returns) */ + + gtk_main (); + + /* Satisfy grumpy compilers */ + + return 0; +} + + + File Selections +

+The file selection widget is a quick and simple way to display a File +dialog box. It comes complete with Ok, Cancel, and Help buttons, a great way +to cut down on programming time. + +To create a new file selection box use: + + +GtkWidget* gtk_file_selection_new (gchar *title); + + +To set the filename, for example to bring up a specific directory, or +give a default filename, use this function: + + +void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename); + + +To grab the text that the user has entered or clicked on, use this +function: + + +gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel); + + +There are also pointers to the widgets contained within the file +selection widget. These are: + + +dir_list +file_list +selection_entry +selection_text +main_vbox +ok_button +cancel_button +help_button + + +Most likely you will want to use the ok_button, cancel_button, and +help_button pointers in signaling their use. + +Included here is an example stolen from testgtk.c, modified to run +on it's own. As you will see, there is nothing much to creating a file +selection widget. While, in this example, the Help button appears on the +screen, it does nothing as there is not a signal attached to it. + + +/* filesel.c */ + +#include + +/* Get the selected filename and print it to the console */ +void file_ok_sel (GtkWidget *w, GtkFileSelection *fs) +{ + g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs))); +} + +void destroy (GtkWidget *widget, gpointer *data) +{ + gtk_main_quit (); +} + +int main (int argc, char *argv[]) +{ + GtkWidget *filew; + + gtk_init (&argc, &argv); + + /* Create a new file selection widget */ + filew = gtk_file_selection_new ("File selection"); + + gtk_signal_connect (GTK_OBJECT (filew), "destroy", + (GtkSignalFunc) destroy, &filew); + /* Connect the ok_button to file_ok_sel function */ + gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button), + "clicked", (GtkSignalFunc) file_ok_sel, filew ); + + /* Connect the cancel_button to destroy the widget */ + gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button), + "clicked", (GtkSignalFunc) gtk_widget_destroy, + GTK_OBJECT (filew)); + + /* Lets set the filename, as if this were a save dialog, and we are giving + a default filename */ + gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew), + "penguin.png"); + + gtk_widget_show(filew); + gtk_main (); + return 0; +} + + Container Widgets @@ -4218,103 +4526,6 @@ Determine if a generic pointer refers to a `GtkListItem' object. Please see the GtkList example on this, which covers the usage of a GtkListItem as well. - - File Selections - -

-The file selection widget is a quick and simple way to display a File -dialog box. It comes complete with Ok, Cancel, and Help buttons, a great way -to cut down on programming time. - -To create a new file selection box use: - - -GtkWidget* gtk_file_selection_new (gchar *title); - - -To set the filename, for example to bring up a specific directory, or -give a default filename, use this function: - - -void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename); - - -To grab the text that the user has entered or clicked on, use this -function: - - -gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel); - - -There are also pointers to the widgets contained within the file -selection widget. These are: - - -dir_list -file_list -selection_entry -selection_text -main_vbox -ok_button -cancel_button -help_button - - -Most likely you will want to use the ok_button, cancel_button, and -help_button pointers in signaling their use. - -Included here is an example stolen from testgtk.c, modified to run -on it's own. As you will see, there is nothing much to creating a file -selection widget. While, in this example, the Help button appears on the -screen, it does nothing as there is not a signal attached to it. - - -/* filesel.c */ - -#include - -/* Get the selected filename and print it to the console */ -void file_ok_sel (GtkWidget *w, GtkFileSelection *fs) -{ - g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs))); -} - -void destroy (GtkWidget *widget, gpointer *data) -{ - gtk_main_quit (); -} - -int main (int argc, char *argv[]) -{ - GtkWidget *filew; - - gtk_init (&argc, &argv); - - /* Create a new file selection widget */ - filew = gtk_file_selection_new ("File selection"); - - gtk_signal_connect (GTK_OBJECT (filew), "destroy", - (GtkSignalFunc) destroy, &filew); - /* Connect the ok_button to file_ok_sel function */ - gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button), - "clicked", (GtkSignalFunc) file_ok_sel, filew ); - - /* Connect the cancel_button to destroy the widget */ - gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button), - "clicked", (GtkSignalFunc) gtk_widget_destroy, - GTK_OBJECT (filew)); - - /* Lets set the filename, as if this were a save dialog, and we are giving - a default filename */ - gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew), - "penguin.png"); - - gtk_widget_show(filew); - gtk_main (); - return 0; -} - - Menu Widgets @@ -4946,6 +5157,89 @@ distclean: clean For now, there's only this example. An explanation and lots 'o' comments will follow later. + + Text Widget + +

+The Text widget allows multiple lines of text to be displayed and edited. It supports both +multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has +a wide set of key based text editing commands, which are compatible with Emacs. + + +Creating and Configuring a Text box +

+There is only one function for creating a new Text widget. + +GtkWidget* gtk_text_new (GtkAdjustment *hadj, + GtkAdjustment *vadj); + + +The arguments allow us to give the Text widget pointers to Adjustments that can be used +to track the viewing position of the widget. Passing NULL values to either or both of +these arguments will cause the gtk_text_new function to create it's own. + + +void gtk_text_set_adjustments (GtkText *text, + GtkAdjustment *hadj, + GtkAdjustment *vadj); + + +The above function allows the horizontal and vertical adjustments of a Text widget to be +changed at any time. + +There are two main ways in which a Text widget can be used: to allow the user to edit a +body of text, or to allow us to display multiple lines of text to the user. In order for +us to switch between these modes of operation, the text widget has the following function: + + +void gtk_text_set_editable (GtkText *text, + gint editable); + + +The +Text Manipulation +

+The current insertion point of a Text widget can be set using + +void gtk_text_set_point (GtkText *text, + guint index); + +where +guint gtk_text_get_point (GtkText *text); + + +A function that is useful in combination with the above two functions is + +guint gtk_text_get_length (GtkText *text); + +which returns the current length of the Text widget. The length is the number of characters +that are within the text block of the widget, including characters such as carriage-return, +which marks the end of lines. + +In order to insert text at the current insertion point of a Text widget, the function +gtk_text_insert is used, which also allows us to specify background and foreground colors and a +font for the text. + + +void gtk_text_insert (GtkText *text, + GdkFont *font, + GdkColor *fore, + GdkColor *back, + const char *chars, + gint length); + + +Passing a value of Undocumented Widgets @@ -4964,9 +5258,6 @@ When you do come to understand all the functions of a new undocumented widget, please consider writing a tutorial on it so others may benifit from your time. - - Color Selections - Range Controls diff --git a/docs/tutorial/gtk_tut.sgml b/docs/tutorial/gtk_tut.sgml index fc85b6c9b..331e05e11 100644 --- a/docs/tutorial/gtk_tut.sgml +++ b/docs/tutorial/gtk_tut.sgml @@ -1552,16 +1552,12 @@ GtkBox GtkImage GtkItem GtkLabel -GtkPaned GtkPixmap GtkScrolledWindow GtkSeparator GtkTable -GtkViewport GtkAspectFrame GtkFrame -GtkVPaned -GtkHPaned GtkVBox GtkHBox GtkVSeparator @@ -3015,15 +3011,6 @@ GtkWidget* gtk_entry_new_with_max_length (guint16 max); The first just creates a new Entry widget, whilst the second creates a new Entry and sets a limit on the length of the text within the Entry.. -The maximum length of the text within an entry widget may be changed by a call to the following -function. If the current text is longer than this maximum, then it is upto us to alter the Entries -contents appropriately. - - -void gtk_entry_set_max_length (GtkEntry *entry, - guint16 max); - - There are several functions for altering the text which is currently within the Entry widget. void gtk_entry_set_text (GtkEntry *entry, @@ -3176,6 +3163,327 @@ int main (int argc, char *argv[]) } + + Color Selection +

+The color selection widget is, not surprisingly, a widget for interactive +selection of colors. This composite widget lets the user select a color by manipulating +RGB (Red, Green, Blue) and HSV (Hue, Saturation, Value) triples. This is done +either by adjusting single values with sliders or entries, or by picking the desired +color from a hue-saturation wheel/value bar. Optionally, the opacity of the color can also +be set. + +The color selection widget currently emits only one signal, "color_changed", which is emitted +whenever the current color in the widget changes, either when the user changes it or if +it's set explicitly through gtk_color_selection_set_color(). + +Lets have a look at what the color selection widget has to offer us. The widget comes +in two flavours; gtk_color_selection and gtk_color_selection_dialog: + + +GtkWidget *gtk_color_selection_new(void); + + +You'll probably not be using this constructor directly. It creates an orphan +GtkColorSelection widget which you'll have to parent yourself. The GtkColorSelection widget +inherits from the GtkVBox widget. + + +GtkWidget *gtk_color_selection_dialog_new(const gchar *title); + + +This is the most common color selection constructor. It creates a GtkColorSelectionDialog, which +inherits from a GtkDialog. It consists of a GtkFrame containing a GtkColorSelection widget, a +GtkHSeparator and a GtkHBox with three buttons, "Ok", "Cancel" and "Help". You can reach these +buttons by accessing the "ok_button", "cancel_button" and "help_button" widgets in the +GtkColorSelectionDialog structure, (i.e. GTK_COLOR_SELECTION_DIALOG(colorseldialog)->ok_button). + + +void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel, + GtkUpdateType policy); + + +This function sets the update policy. The default policy is GTK_UPDATE_CONTINOUS which means that +the current color is updated continously when the user drags the sliders or presses the mouse and drags +in the hue-saturation wheel or value bar. If you experience performance problems, you may +want to set the policy to GTK_UPDATE_DISCONTINOUS or GTK_UPDATE_DELAYED. + + +void gtk_color_selection_set_opacity(GtkColorSelection *colorsel, + gint use_opacity); + + +The color selection widget supports adjusting the opacity of a color (also known as the alpha channel). +This is disabled by default. Calling this function with use_opacity set to TRUE enables opacity. +Likewise, use_opacity set to FALSE will disable opacity. + + +void gtk_color_selection_set_color(GtkColorSelection *colorsel, + gdouble *color); + + +You can set the current color explicitly by calling this function with a pointer to an array +of colors (gdouble). The length of the array depends on whether opacity is enabled or not. +Position 0 contains the red component, 1 is green, 2 is blue and opacity is at position 3 (only if +opacity is enabled, see gtk_color_selection_set_opacity()). All values are between 0.0 and 1.0. + + +void gtk_color_selection_get_color(GtkColorSelection *colorsel, + gdouble *color); + + +When you need to query the current color, typically when you've received a "color_changed" signal, +you use this function. Color is a pointer to the array of colors to fill in. See the +gtk_color_selection_set_color() function for the description of this array. + + + +Here's a simple example demonstrating the use of the GtkColorSelectionDialog. The program displays a window +containing a drawing area. Clicking on it opens a color selection dialog, and changing the color in the +color selection dialog changes the background color. + + +#include +#include +#include + +GtkWidget *colorseldlg = NULL; +GtkWidget *drawingarea = NULL; + +/* Color changed handler */ + +void color_changed_cb (GtkWidget *widget, GtkColorSelection *colorsel) +{ + gdouble color[3]; + GdkColor gdk_color; + GdkColormap *colormap; + + /* Get drawingarea colormap */ + + colormap = gdk_window_get_colormap (drawingarea->window); + + /* Get current color */ + + gtk_color_selection_get_color (colorsel,color); + + /* Fit to a unsigned 16 bit integer (0..65535) and insert into the GdkColor structure */ + + gdk_color.red = (guint16)(color[0]*65535.0); + gdk_color.green = (guint16)(color[1]*65535.0); + gdk_color.blue = (guint16)(color[2]*65535.0); + + /* Allocate color */ + + gdk_color_alloc (colormap, &gdk_color); + + /* Set window background color */ + + gdk_window_set_background (drawingarea->window, &gdk_color); + + /* Clear window */ + + gdk_window_clear (drawingarea->window); +} + +/* Drawingarea event handler */ + +gint area_event (GtkWidget *widget, GdkEvent *event, gpointer client_data) +{ + gint handled = FALSE; + GtkWidget *colorsel; + + /* Check if we've received a button pressed event */ + + if (event->type == GDK_BUTTON_PRESS && colorseldlg == NULL) + { + /* Yes, we have an event and there's no colorseldlg yet! */ + + handled = TRUE; + + /* Create color selection dialog */ + + colorseldlg = gtk_color_selection_dialog_new("Select background color"); + + /* Get the GtkColorSelection widget */ + + colorsel = GTK_COLOR_SELECTION_DIALOG(colorseldlg)->colorsel; + + /* Connect to the "color_changed" signal, set the client-data to the colorsel widget */ + + gtk_signal_connect(GTK_OBJECT(colorsel), "color_changed", + (GtkSignalFunc)color_changed_cb, (gpointer)colorsel); + + /* Show the dialog */ + + gtk_widget_show(colorseldlg); + } + + return handled; +} + +/* Close down and exit handler */ + +void destroy_window (GtkWidget *widget, gpointer client_data) +{ + gtk_main_quit (); +} + +/* Main */ + +gint main (gint argc, gchar *argv[]) +{ + GtkWidget *window; + + /* Initialize the toolkit, remove gtk-related commandline stuff */ + + gtk_init (&argc,&argv); + + /* Create toplevel window, set title and policies */ + + window = gtk_window_new (GTK_WINDOW_TOPLEVEL); + gtk_window_set_title (GTK_WINDOW(window), "Color selection test"); + gtk_window_set_policy (GTK_WINDOW(window), TRUE, TRUE, TRUE); + + /* Attach to the "delete" and "destroy" events so we can exit */ + + gtk_signal_connect (GTK_OBJECT(window), "delete_event", + (GtkSignalFunc)destroy_window, (gpointer)window); + + gtk_signal_connect (GTK_OBJECT(window), "destroy", + (GtkSignalFunc)destroy_window, (gpointer)window); + + /* Create drawingarea, set size and catch button events */ + + drawingarea = gtk_drawing_area_new (); + + gtk_drawing_area_size (GTK_DRAWING_AREA(drawingarea), 200, 200); + + gtk_widget_set_events (drawingarea, GDK_BUTTON_PRESS_MASK); + + gtk_signal_connect (GTK_OBJECT(drawingarea), "event", + (GtkSignalFunc)area_event, (gpointer)drawingarea); + + /* Add drawingarea to window, then show them both */ + + gtk_container_add (GTK_CONTAINER(window), drawingarea); + + gtk_widget_show (drawingarea); + gtk_widget_show (window); + + /* Enter the gtk main loop (this never returns) */ + + gtk_main (); + + /* Satisfy grumpy compilers */ + + return 0; +} + + + File Selections +

+The file selection widget is a quick and simple way to display a File +dialog box. It comes complete with Ok, Cancel, and Help buttons, a great way +to cut down on programming time. + +To create a new file selection box use: + + +GtkWidget* gtk_file_selection_new (gchar *title); + + +To set the filename, for example to bring up a specific directory, or +give a default filename, use this function: + + +void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename); + + +To grab the text that the user has entered or clicked on, use this +function: + + +gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel); + + +There are also pointers to the widgets contained within the file +selection widget. These are: + + +dir_list +file_list +selection_entry +selection_text +main_vbox +ok_button +cancel_button +help_button + + +Most likely you will want to use the ok_button, cancel_button, and +help_button pointers in signaling their use. + +Included here is an example stolen from testgtk.c, modified to run +on it's own. As you will see, there is nothing much to creating a file +selection widget. While, in this example, the Help button appears on the +screen, it does nothing as there is not a signal attached to it. + + +/* filesel.c */ + +#include + +/* Get the selected filename and print it to the console */ +void file_ok_sel (GtkWidget *w, GtkFileSelection *fs) +{ + g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs))); +} + +void destroy (GtkWidget *widget, gpointer *data) +{ + gtk_main_quit (); +} + +int main (int argc, char *argv[]) +{ + GtkWidget *filew; + + gtk_init (&argc, &argv); + + /* Create a new file selection widget */ + filew = gtk_file_selection_new ("File selection"); + + gtk_signal_connect (GTK_OBJECT (filew), "destroy", + (GtkSignalFunc) destroy, &filew); + /* Connect the ok_button to file_ok_sel function */ + gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button), + "clicked", (GtkSignalFunc) file_ok_sel, filew ); + + /* Connect the cancel_button to destroy the widget */ + gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button), + "clicked", (GtkSignalFunc) gtk_widget_destroy, + GTK_OBJECT (filew)); + + /* Lets set the filename, as if this were a save dialog, and we are giving + a default filename */ + gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew), + "penguin.png"); + + gtk_widget_show(filew); + gtk_main (); + return 0; +} + + Container Widgets @@ -4218,103 +4526,6 @@ Determine if a generic pointer refers to a `GtkListItem' object. Please see the GtkList example on this, which covers the usage of a GtkListItem as well. - - File Selections - -

-The file selection widget is a quick and simple way to display a File -dialog box. It comes complete with Ok, Cancel, and Help buttons, a great way -to cut down on programming time. - -To create a new file selection box use: - - -GtkWidget* gtk_file_selection_new (gchar *title); - - -To set the filename, for example to bring up a specific directory, or -give a default filename, use this function: - - -void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename); - - -To grab the text that the user has entered or clicked on, use this -function: - - -gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel); - - -There are also pointers to the widgets contained within the file -selection widget. These are: - - -dir_list -file_list -selection_entry -selection_text -main_vbox -ok_button -cancel_button -help_button - - -Most likely you will want to use the ok_button, cancel_button, and -help_button pointers in signaling their use. - -Included here is an example stolen from testgtk.c, modified to run -on it's own. As you will see, there is nothing much to creating a file -selection widget. While, in this example, the Help button appears on the -screen, it does nothing as there is not a signal attached to it. - - -/* filesel.c */ - -#include - -/* Get the selected filename and print it to the console */ -void file_ok_sel (GtkWidget *w, GtkFileSelection *fs) -{ - g_print ("%s\n", gtk_file_selection_get_filename (GTK_FILE_SELECTION (fs))); -} - -void destroy (GtkWidget *widget, gpointer *data) -{ - gtk_main_quit (); -} - -int main (int argc, char *argv[]) -{ - GtkWidget *filew; - - gtk_init (&argc, &argv); - - /* Create a new file selection widget */ - filew = gtk_file_selection_new ("File selection"); - - gtk_signal_connect (GTK_OBJECT (filew), "destroy", - (GtkSignalFunc) destroy, &filew); - /* Connect the ok_button to file_ok_sel function */ - gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION (filew)->ok_button), - "clicked", (GtkSignalFunc) file_ok_sel, filew ); - - /* Connect the cancel_button to destroy the widget */ - gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION (filew)->cancel_button), - "clicked", (GtkSignalFunc) gtk_widget_destroy, - GTK_OBJECT (filew)); - - /* Lets set the filename, as if this were a save dialog, and we are giving - a default filename */ - gtk_file_selection_set_filename (GTK_FILE_SELECTION(filew), - "penguin.png"); - - gtk_widget_show(filew); - gtk_main (); - return 0; -} - - Menu Widgets @@ -4946,6 +5157,89 @@ distclean: clean For now, there's only this example. An explanation and lots 'o' comments will follow later. + + Text Widget + +

+The Text widget allows multiple lines of text to be displayed and edited. It supports both +multi-colored and multi-font text, allowing them to be mixed in any way we wish. It also has +a wide set of key based text editing commands, which are compatible with Emacs. + + +Creating and Configuring a Text box +

+There is only one function for creating a new Text widget. + +GtkWidget* gtk_text_new (GtkAdjustment *hadj, + GtkAdjustment *vadj); + + +The arguments allow us to give the Text widget pointers to Adjustments that can be used +to track the viewing position of the widget. Passing NULL values to either or both of +these arguments will cause the gtk_text_new function to create it's own. + + +void gtk_text_set_adjustments (GtkText *text, + GtkAdjustment *hadj, + GtkAdjustment *vadj); + + +The above function allows the horizontal and vertical adjustments of a Text widget to be +changed at any time. + +There are two main ways in which a Text widget can be used: to allow the user to edit a +body of text, or to allow us to display multiple lines of text to the user. In order for +us to switch between these modes of operation, the text widget has the following function: + + +void gtk_text_set_editable (GtkText *text, + gint editable); + + +The +Text Manipulation +

+The current insertion point of a Text widget can be set using + +void gtk_text_set_point (GtkText *text, + guint index); + +where +guint gtk_text_get_point (GtkText *text); + + +A function that is useful in combination with the above two functions is + +guint gtk_text_get_length (GtkText *text); + +which returns the current length of the Text widget. The length is the number of characters +that are within the text block of the widget, including characters such as carriage-return, +which marks the end of lines. + +In order to insert text at the current insertion point of a Text widget, the function +gtk_text_insert is used, which also allows us to specify background and foreground colors and a +font for the text. + + +void gtk_text_insert (GtkText *text, + GdkFont *font, + GdkColor *fore, + GdkColor *back, + const char *chars, + gint length); + + +Passing a value of Undocumented Widgets @@ -4964,9 +5258,6 @@ When you do come to understand all the functions of a new undocumented widget, please consider writing a tutorial on it so others may benifit from your time. - - Color Selections - Range Controls