/* Gtk+ User Interface Builder * Copyright (C) 1998 Damon Chaplin * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */ #ifndef GLADE_UTILS_H #define GLADE_UTILS_H #include #include #include #include #include #include #include #include #include #include "gbwidget.h" #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /* Days of the week, 'Sun' ... 'Sat'. */ extern gchar *GladeDayNames[]; /* Months of the year, 'Jan' ... 'Dec'. */ extern gchar *GladeMonthNames[]; /* This shows a simple dialog box with a label and an 'OK' button. If transient_widget is not NULL, then its toplevel window is found and used to set the transient_for property (this also works for menu widgets). Example usage: glade_util_show_message_box ("Error saving file", NULL); */ void glade_util_show_message_box (const gchar *message, GtkWidget *transient_widget); /* This creates a dialog box with a message and a number of buttons. * Signal handlers can be supplied for any of the buttons. * NOTE: The dialog is automatically destroyed when any button is clicked. * default_button specifies the default button, numbered from 1.. * data is passed to the signal handler. Example usage: gchar *buttons[] = { "Yes", "No", "Cancel" }; GtkSignalFunc signal_handlers[] = { on_yes, on_no, NULL }; glade_util_show_dialog ("Do you want to save the current project?", 3, buttons, 3, signal_handlers, NULL); */ GtkWidget* glade_util_create_dialog_with_buttons (const gchar *message, gint nbuttons, const gchar *buttons[], gint default_button, GtkSignalFunc signal_handlers[], gpointer data, GtkWidget *transient_widget); /* This shows a dialog box with a message and an Entry for entering a value. * When the OK button is pressed the handler of the specified widget will * be called with the value and the given data. * NOTE: The dialog is automatically destroyed when any button is clicked. Example usage: glade_util_show_entry_dialog ("Name:", "default", widget, on_dialog_ok, "NewName"); void on_dialog_ok(GtkWidget *widget, gchar *value, gpointer data) { ... */ typedef gint (*GbEntryDialogFunc) (GtkWidget *widget, gchar *value, gpointer data); void glade_util_show_entry_dialog(const gchar *message, const gchar *initial_value, GtkWidget *widget, GbEntryDialogFunc signal_handler, gpointer data, GtkWidget *transient_widget); /* This creates a dialog with OK & Cancel buttons, usable in plain GTK or Gnome, and returns a vbox which the caller can place widgets in. If transient_for is non-NULL, the window it is in is used to set the transient for relationship, so the dialog will always be above the widget. The callback will be called when the OK button is pressed. */ GtkWidget* glade_util_create_dialog (const gchar *title, GtkWidget *transient_for, GtkSignalFunc ok_handler, gpointer ok_handler_data, GtkWidget **vbox); typedef enum { GladeEscCloses, GladeEscDestroys } GladeEscAction; /* This event handler performs the selected GladeEscAction when Esc is pressed in a dialog. It is not necessary for GnomeDialogs. */ gint glade_util_check_key_is_esc (GtkWidget *widget, GdkEventKey *event, gpointer data); /* This returns a new entry ready to insert in a dialog. The entry is set up so that will invoke the default action. The returned widget must be added to a container in the dialog. */ extern GtkWidget * glade_util_entry_new (GtkObject *dialog); /* This returns a new spinbutton ready to insert in a dialog. A pointer to the spin button is added as object data to the dialog. The spinbutton is set up so that will invoke the default action. The returned widget must be added to a container in the dialog. */ extern GtkWidget * glade_util_spin_button_new (GtkObject *dialog, const gchar *key, GtkAdjustment *adjustment, gfloat climb_rate, guint digits); /* This returns the index of the given gint with the given array of gints. If the value is not found it outputs a warning and returns -1. This function is intended to be used for finding the index when using properties which are choices. */ gint glade_util_int_array_index (const gint array[], gint array_size, gint value); /* This returns the index of the given string with the given array of strings. If the value is not found it outputs a warning and returns -1. This function is intended to be used for finding the index when using properties which are choices. */ gint glade_util_string_array_index (const gchar *array[], gint array_size, const gchar *value); /* This returns TRUE if the two strings are equivalent. Note that NULL is considered equivalent to the empty string. */ gboolean glade_util_strings_equivalent (const gchar *string1, const gchar *string2); /* This returns a copy of the given string, or NULL if the string is NULL or empty, i.e. "". */ gchar* glade_util_copy_string (const gchar *string); /* Returns TRUE if string contains substring. Returns FALSE if substring is not found or is NULL. */ gboolean glade_util_strstr (const gchar *string, const gchar *substring); gchar* glade_util_find_start_of_tag_name (const gchar * tag_name); gchar* glade_util_create_modifiers_string (guint8 modifier_flags); /* parse a string in the form of "GTK_ANCHOR_NE|GTK_ANCHOR_SW" */ guint glade_util_flags_from_string (GType type, const char *string); gchar* glade_util_string_from_flags (GType type, guint flags); const char *glade_string_from_enum (GType type, gint value); gint glade_enum_from_string (GType type, const char *string); /* This creates a GtkPixmap widget, using a colormap and xpm data from an '#include'd pixmap file. */ GtkWidget* glade_util_create_pixmap_using_colormap (GdkColormap *colormap, gchar **xpm_data); /* This returns TRUE if the widget is a toplevel project component, i.e. a window, dialog or popup menu. */ gboolean glade_util_is_component (GtkWidget *widget); /* This returns the toplevel widget containing the given widget. It is similar to gtk_widget_get_toplevel() but is also walks up menus. */ GtkWidget* glade_util_get_toplevel (GtkWidget *widget); /* This returns the closest ancestor of the given widget which is a GbWidget.*/ GtkWidget* glade_util_get_parent (GtkWidget *widget); /* This tries to find a named widget in a component. It returns the widget or NULL if it wasn't found. */ GtkWidget* glade_util_find_widget (GtkWidget *widget, gchar *name); /* This is used when setting up keyboard accelerators resulting from underlined keys in labels. It returns the mnemonic widget to use. */ GtkWidget* glade_util_find_default_accelerator_target (GtkWidget *label); /* Returns the index of a widget in a box. Note that the box packing property means that widgets may not be displayed in this order. */ gint glade_util_get_box_pos (GtkBox *box, GtkWidget *widget); /* Returns the structure corresponding to the given widget in a table. */ GtkTableChild* glade_util_find_table_child (GtkTable *table, GtkWidget *widget); GtkBoxChild* glade_util_find_box_child (GtkBox *box, GtkWidget *widget); GtkFixedChild* glade_util_find_fixed_child (GtkFixed *fixed, GtkWidget *widget); #if GLADE_SUPPORTS_GTK_PACKER GtkPackerChild* glade_util_find_packer_child (GtkPacker *packer, GtkWidget *widget); #endif /* This returns the GtkLabel's text, including the underline characters. It is needed since GtkLabel doesn't provide the opposite function to gtk_label_parse_uline(). The returned string should be freed after use. */ gchar* glade_util_get_label_text (GtkWidget *label); /* These close the given window, so that if it is shown again it appears in the same place. */ gint glade_util_close_window_on_delete (GtkWidget *widget, GdkEvent *event, gpointer data); gint glade_util_close_window (GtkWidget *widget); /* * File Utility Functions. */ /* Returns TRUE if the given file exists. filename must be UTF-8. */ gboolean glade_util_file_exists (const gchar *filename); /* Returns the last modification time of the given file, or 0 if it doesn't exist, or -1 on error. filename must be UTF-8. */ GladeError* glade_util_file_last_mod_time (const gchar *filename, time_t *last_mod_time); /* This copies a file from src to dest, and returns a GladeError if an error occurs. src & dest must be UTF-8. */ GladeError* glade_util_copy_file (const gchar *src, const gchar *dest); /* Creates a directory if it doesn't already exist. */ GladeError* glade_util_ensure_directory_exists (const gchar *directory); /* * Filename Utility Functions. */ /* Adds a filename onto a directory to make a complete pathname. The directory may or may not end in '/'. file must be a simple filename. Free the returned string when no longer needed. */ gchar* glade_util_make_path (const gchar *dir, const gchar *file); /* This turns a relative pathname into an absolute one based on the given base directory (which MUST be absolute). e.g. "/home/damon" + "../dave/test" -> "/home/dave/test" The returned path should be freed when no longer needed. */ gchar* glade_util_make_absolute_path (const gchar *dir, const gchar *file); /* This turns an absolute pathname into an relative one based on the given base directory. Both arguments must be absolute paths, and should be in canonical form, i.e. not containing '..', '.' or multiple '/'s together. The returned value may or may not end with a '/', depending on the arguments. The returned path should be freed when no longer needed. */ gchar* glade_util_make_relative_path (const gchar *base_dir, const gchar *file); /* Returns TRUE if file is in dir. Both paths must be absolute. file can be a directory, and both can end in '/' or not. Note that we assume that both are in proper form, i.e. there are no instances of '//', '.', or '..' in either. */ gboolean glade_util_directory_contains_file (const gchar *dir, const gchar *file); /* Returns TRUE if the 2 directories are equivalent. Both must be absolute paths, and may or may not end in '/'. */ gboolean glade_util_directories_equivalent (const gchar *dir1, const gchar *dir2); /* This is similar to GLib's dirname, but it makes sure the dirname ends with a G_DIR_SEPARATOR. */ gchar* glade_util_dirname (const gchar *file_name); /* This returns the parent directory of the given directory, which may or may not end in a G_DIR_SEPARATOR. The returned string should be freed. */ gchar* glade_util_parent_directory (const gchar *dir); /* This searches the $HOME/Projects directory to find the default directory to use for the next project, e.g. $HOME/Projects/project1. The returned directory should be freed when no longer needed. */ GladeError* glade_util_get_next_free_project_directory (gchar **project_directory_return, gint *project_num_return); /* Sets the TZ environment variable to the given value, e.g. "UTC", returning the old setting. NOTE: You must call glade_util_reset_timezone() some time later to restore the original TZ. Pass glade_util_reset_timezone() the string that glade_util_set_timezone() returns. */ gchar* glade_util_set_timezone (const gchar *tz); void glade_util_reset_timezone (gchar *tz); gboolean glade_util_check_is_stock_id (const gchar *stock_id); /* This is a GCompareFunc for comparing the labels of 2 stock items, ignoring any '_' characters. It isn't particularly efficient. */ gint glade_util_compare_stock_labels (gconstpointer a, gconstpointer b); /* FIXME: These are pinched from gtkcombo.c. Get rid of them. */ /* GtkListItem *glade_util_gtk_combo_find (GtkCombo *combo);*/ /*gchar *glade_util_gtk_combo_func (GtkListItem *listitem);*/ gpointer glade_util_gtk_combo_find (GtkCombo *combo); gchar *glade_util_gtk_combo_func (gpointer listitem); /* Returns TRUE if we need to support a 'Border Width' property for a widget.*/ gboolean glade_util_uses_border_width (GtkWidget *widget); /* Converts a filename from UTF-8 to on-disk encoding, and sets it in a GtkFileSelection. */ void glade_util_set_file_selection_filename(GtkWidget *filesel, const gchar *filename_utf8); /* Gets the selected file in a GtkFileSelection, converts it to UTF-8 and returns it. Note that the returned string must be freed. */ gchar* glade_util_get_file_selection_filename(GtkWidget *filesel); /* Like fopen but takes a UTF-8 filename and converts to on-disk encoding. */ FILE* glade_util_fopen (const gchar *filename_utf8, const gchar *mode); /* Gets a list of file names from a text/uri-list */ GList *glade_util_uri_list_parse (const gchar *uri_list); /* Gets the extra translation properties stored inside the widget data. */ void glade_util_get_translation_properties (GtkWidget *widget, const gchar *property_name, gboolean *translatable, gchar **comments, gboolean *context); /* Sets the extra translation properties stored inside the widget data. */ void glade_util_set_translation_properties (GtkWidget *widget, const gchar *property_name, gboolean translatable, const gchar *comments, gboolean context); /* Copies the extra translation properties stored inside the widget data. */ void glade_util_copy_translation_properties(GtkWidget *from_widget, const gchar *from_property_name, GtkWidget *to_widget, const gchar *to_property_name); #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* GLADE_UTILS_H */