Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

- New subsection on colourselection from Tom Bech <tomb@ii.uib.no> - Moved

Browse Source 
Mon Mar 16 09:15:03 GMT 1998 Tony Gale  <gale@gimp.org>

        * docs/gtk_tut.sgml:
            - New subsection on colourselection from Tom Bech <tomb@ii.uib.no>
            - 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.
This commit is contained in:
GMT 1998 Tony Gale
1998-03-16 09:25:13 +00:00
committed by Tony Gale
parent 27c086bd95
commit 60c008eb99
9 changed files with 871 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files

517
docs/tutorial/gtk_tut.sgml
View File

@@ -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.
<tscreen><verb>
void gtk_entry_set_max_length (GtkEntry *entry,
guint16 max);
</verb></tscreen>
There are several functions for altering the text which is currently within the Entry widget.
<tscreen><verb>
void gtk_entry_set_text (GtkEntry *entry,
@@ -3176,6 +3163,327 @@ int main (int argc, char *argv[])
}
</verb></tscreen>
<!-- ----------------------------------------------------------------- -->
<sect1> Color Selection
<P>
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:
<tscreen><verb>
GtkWidget *gtk_color_selection_new(void);
</verb></tscreen>
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.
<tscreen><verb>
GtkWidget *gtk_color_selection_dialog_new(const gchar *title);
</verb></tscreen>
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).
<tscreen><verb>
void gtk_color_selection_set_update_policy(GtkColorSelection *colorsel,
GtkUpdateType policy);
</verb></tscreen>
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.
<tscreen><verb>
void gtk_color_selection_set_opacity(GtkColorSelection *colorsel,
gint use_opacity);
</verb></tscreen>
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.
<tscreen><verb>
void gtk_color_selection_set_color(GtkColorSelection *colorsel,
gdouble *color);
</verb></tscreen>
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.
<tscreen><verb>
void gtk_color_selection_get_color(GtkColorSelection *colorsel,
gdouble *color);
</verb></tscreen>
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.
<!-- Need to do a whole section on DnD - TRG
Drag and drop
-------------
The color sample areas (right under the hue-saturation wheel) supports drag and drop. The type of
drag and drop is "application/x-color". The message data consists of an array of 4
(or 5 if opacity is enabled) gdouble values, where the value at position 0 is 0.0 (opacity
on) or 1.0 (opacity off) followed by the red, green and blue values at positions 1,2 and 3 respectively.
If opacity is enabled, the opacity is passed in the value at position 4.
-->
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.
<tscreen><verb>
#include <glib.h>
#include <gdk/gdk.h>
#include <gtk/gtk.h>
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, &amp;gdk_color);
/* Set window background color */
gdk_window_set_background (drawingarea->window, &amp;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 &amp;&amp; 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 (&amp;argc,&amp;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;
}
</verb></tscreen>
<!-- ----------------------------------------------------------------- -->
<sect1> File Selections
<p>
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:
<tscreen><verb>
GtkWidget* gtk_file_selection_new (gchar *title);
</verb></tscreen>
To set the filename, for example to bring up a specific directory, or
give a default filename, use this function:
<tscreen><verb>
void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);
</verb></tscreen>
To grab the text that the user has entered or clicked on, use this
function:
<tscreen><verb>
gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);
</verb></tscreen>
There are also pointers to the widgets contained within the file
selection widget. These are:
<itemize>
<item>dir_list
<item>file_list
<item>selection_entry
<item>selection_text
<item>main_vbox
<item>ok_button
<item>cancel_button
<item>help_button
</itemize>
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.
<tscreen><verb>
/* filesel.c */
#include <gtk/gtk.h>
/* 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 (&amp;argc, &amp;argv);
/* Create a new file selection widget */
filew = gtk_file_selection_new ("File selection");
gtk_signal_connect (GTK_OBJECT (filew), "destroy",
(GtkSignalFunc) destroy, &amp;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;
}
</verb></tscreen>
<!-- ***************************************************************** -->
<sect> 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.
<!-- ***************************************************************** -->
<sect> File Selections
<!-- ***************************************************************** -->
<p>
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:
<tscreen><verb>
GtkWidget* gtk_file_selection_new (gchar *title);
</verb></tscreen>
To set the filename, for example to bring up a specific directory, or
give a default filename, use this function:
<tscreen><verb>
void gtk_file_selection_set_filename (GtkFileSelection *filesel, gchar *filename);
</verb></tscreen>
To grab the text that the user has entered or clicked on, use this
function:
<tscreen><verb>
gchar* gtk_file_selection_get_filename (GtkFileSelection *filesel);
</verb></tscreen>
There are also pointers to the widgets contained within the file
selection widget. These are:
<itemize>
<item>dir_list
<item>file_list
<item>selection_entry
<item>selection_text
<item>main_vbox
<item>ok_button
<item>cancel_button
<item>help_button
</itemize>
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.
<tscreen><verb>
/* filesel.c */
#include <gtk/gtk.h>
/* 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 (&amp;argc, &amp;argv);
/* Create a new file selection widget */
filew = gtk_file_selection_new ("File selection");
gtk_signal_connect (GTK_OBJECT (filew), "destroy",
(GtkSignalFunc) destroy, &amp;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;
}
</verb></tscreen>
<!-- ***************************************************************** -->
<sect>Menu Widgets
<!-- ***************************************************************** -->
@@ -4946,6 +5157,89 @@ distclean: clean
For now, there's only this example. An explanation and lots 'o' comments
will follow later.
<!-- ***************************************************************** -->
<sect> Text Widget
<!-- ***************************************************************** -->
<p>
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.
<!-- ----------------------------------------------------------------- -->
<sect1>Creating and Configuring a Text box
<p>
There is only one function for creating a new Text widget.
<tscreen><verb>
GtkWidget* gtk_text_new (GtkAdjustment *hadj,
GtkAdjustment *vadj);
</verb></tscreen>
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.
<tscreen><verb>
void gtk_text_set_adjustments (GtkText *text,
GtkAdjustment *hadj,
GtkAdjustment *vadj);
</verb></tscreen>
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:
<tscreen><verb>
void gtk_text_set_editable (GtkText *text,
gint editable);
</verb></tscreen>
The <tt/editable/ argument is a TRUE or FALSE value that specifies whether the user is
permitted to edit the contents of the Text widget. When the text widget is editable, it
will display a cursor at the current insertion point.
<!-- ----------------------------------------------------------------- -->
<sect1>Text Manipulation
<P>
The current insertion point of a Text widget can be set using
<tscreen><verb>
void gtk_text_set_point (GtkText *text,
guint index);
</verb></tscreen>
where <tt/index/ is the position to set the insertion point.
Analogous to this is the function for getting the current insertion point:
<tscreen><verb>
guint gtk_text_get_point (GtkText *text);
</verb></tscreen>
A function that is useful in combination with the above two functions is
<tscreen><verb>
guint gtk_text_get_length (GtkText *text);
</verb></tscreen>
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.
<tscreen><verb>
void gtk_text_insert (GtkText *text,
GdkFont *font,
GdkColor *fore,
GdkColor *back,
const char *chars,
gint length);
</verb></tscreen>
Passing a value of <tt/NULL/ in as the value for the foreground color, background colour or
font will result in the values set within the widget style to be used. Using a value of <tt/-1/ for
the length parameter will result in the whole of the text string given to be inserted.
<!-- ***************************************************************** -->
<sect> 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.
<!-- ----------------------------------------------------------------- -->
<sect1> Color Selections
<!-- ----------------------------------------------------------------- -->
<sect1> Range Controls