Nautilus Gtk stuff inventory (for Gtk 2.0?)

[Darin Adler <darin eazel com>]

The programmers at Eazel said that we do not have enough time to roll things
into Gtk+ in time for 2.0. But maybe that was overstating the case. For one
thing we have at least one thing we really should roll in (drag changes that
Pavel is working on now).

I figured it might still be good to give an inventory of things in Nautilus
that are Gtk+ extensions, or extensions to things in Gnome that someone is
perhaps moving into Gtk+ for 2.0.

If any of these sound particularly interesting for Gtk+ 2.0 (I'm really
looking for feedback from the maintainers or other highly-interested,
highly-involved parties), I could be coaxed to put in the effort to get a
patch done in time for the feature freeze; knowing that a maintainer is
specifically interested would provide the additional motivation. Otherwise,
considering moving these out of Nautilus can wait for a future version (next
year or whatever).

Of course anyone outside Eazel is welcome to do this regardless of the
response to this email!

These are not carefully organized or complete or even all carefully named,
just the pile of stuff we have needed so far as we are implementing
Nautilus.

-----------------
nautilus-string.h
-----------------
    nautilus_strlen (returns 0 for NULL, following g_strdup's lead of
allowing NULL)
    nautilus_strchr (returns NULL for NULL, following g_strdup's lead of
allowing NULL)
    nautilus_strcmp (allows NULLs, following g_strdup's lead of allowing
NULL, currently NULL == "", but we could change definition so that NULL ==
NULL only instead)
    nautilus_strcasecmp (allows NULLs as nautilus_strcmp does)
    nautilus_str_compare (nautilus_strcmp with GCompareFunc-style
parameters)

    nautilus_eat_strcmp (nautilus_strcmp with g_free on one of the two
strings; not really so useful)

    nautilus_str_is_empty (s == NULL || s[0] == '\0'; provided so people
won't do strlen (s) == 0 or something like that)
    nautilus_str_has_prefix (provided so people won't do strstr (s) == s or
something like that; heavily used)
    nautilus_str_has_suffix

    nautilus_str_get_prefix (makes dup of string up to a delimiter)
    nautilus_str_strip_chr (make dup that removes all instances of a
character)
    nautilus_str_strip_trailing_chr (make dup that removes all trailing
instances of a character)

    nautilus_str_to_int (nicer interface for one particular sscanf case)
    nautilus_eat_str_to_int (nautilus_str_to_int + g_free)

    nautilus_str_escape_slashes (makes dup with "/" -> "\/" and "\" -> "\\";
used to turn path name into file name)
    nautilus_str_double_underscores (makes dup with "_" -> "__"; makes
underscores work in gtk menu items)

    nautilus_str_capitalize (g_strdup (g_strup))

--------------------------
nautilus-glib-extensions.h
--------------------------
    nautilus_boolean_bit (unsigned type to use instead of gboolean in a bit
field)
    NAUTILUS_N_ELEMENTS (already in HEAD I believe)

    nautilus_g_date_new_tm (create a GDate given a struct tm)
    nautilus_strdup_strftime (calls strftime in a safe way, like
g_strdup_printf)

    nautilus_g_list_exactly_one_item (fast, to avoid g_list_length == 1
code)
    nautilus_g_list_more_than_one_item (fast, to avoid g_list_length > 1
code)
    nautilus_g_list_equal (compares pointers)
    nautilus_g_list_copy (already in HEAD I think)
    nautilus_g_list_safe_for_each (allows deletion of current item in
callback, needs a better name probably, or at least you probably want to
cram for_each into one "word")
    nautilus_g_list_partition (breaks list into two pieces based on
predicate callback)
    nautilus_g_list_free_deep (g_list_foreach (g_free) + g_list_free)
    nautilus_g_list_free_deep_custom (g_list_foreach (f) + g_list_free)

    nautilus_str_list_equal (compares strings with nautilus_strcmp)
    nautilus_str_list_copy (copies strings with g_strdup)
    nautilus_str_list_sort (g_list_sort (nautilus_strcmp))
    nautilus_str_list_sort_case_insensitive (g_list_sort
(nautilus_strcasecmp))

    nautilus_g_ptr_array_new_from_list (turns GList into GPtrArray)
    nautilus_g_ptr_array_sort (like a cover for qsort)
    nautilus_g_ptr_array_search (like a cover for bsearch)

    nautilus_g_strv_find (uses strcmp but NULL-tolerant)

    nautilus_get_system_time (turns gettimeofday result into gint64)

-------------------------
nautilus-gdk-extensions.h
-------------------------
    NAUTILUS_RGB_COLOR_WHITE (24-bit RGB values)
    NAUTILUS_RGB_COLOR_BLACK
    NAUTILUS_RGB_COLOR_RED
    NAUTILUS_RGB_COLOR_GREEN
    NAUTILUS_RGB_COLOR_BLUE

    nautilus_gradient_* (set of calls for manipulating a string with a
gradient spec. in it)

    nautilus_gdk_color_parse_with_default (returns default color instead of
boolean fail indicator)
    nautilus_gdk_color_parse_with_white_default (returns default color
instead of boolean fail indicator)
    nautilus_parse_rgb_with_default (returns RGB value instead of GdkColor)
    nautilus_parse_rgb_with_white_default (returns RGB value instead of
GdkColor)

    nautilus_fill_rectangle (takes GdkRectangle instead of 4 integers)
    nautilus_fill_rectangle_with_color (uses RGB for color instead of
foreground)
    nautilus_fill_rectangle-with_gradient (takes 2 RGBs and a direction)

    nautilus_stipple_bitmap (returns GdkBitmap with standard 50% stipple
used for many kinds of highlighting and graphic effects)

    nautilus_rectangle_contains (checks if point is in rectangle)
    nautilus_rectangle_inset (moves edges of rectangle towards or away from
center by specified amount)

    nautilus_interpolate_color (finds RGB value betwen two RGB values;
currently uses simple calculation but could use perceptual space instead;
used for gradients)

    nautilus_gdk_font_equal (allows NULLs)
    nautilus_get_largest_fitting_font (finds a particular size of font given
space to fit in)

-------------------------
nautilus-gtk-extensions.h
-------------------------
    nautilus_gtk_button_auto_click (arranges for a button to look and like
it was clicked; you see the down and up on screen)
    nautilus_gtk_button_set_padding (puts a specified amount of padding
around it)

    nautilus_gtk_clist_get_first_selected_row (returns row number or -1)
    nautilus_gtk_clist_get_last_selected_row (returns row number or -1)
    nautilus_gtk_clist_set_double_click_button (makes double click do an
auto-clock on the passed-in button)

    nautilus_gtk_signal_connect_free_data (gtk_connect_full cover for the
common case where you just want g_free for the destroy notify function)
    nautilus_gtk_signal_connect_free_data_custom (gtk_connect + just the
destroy-notify [not as full as gtk_connect_full]; not so useful)
    nautilus_gtk_signal_connect_full_while_alive (version of
connect_while_alive that works with destroy notify [and all other options])

    nautilus_gtk_object_list_ref (g_list_foreach (gtk_object_ref))
    nautilus_gtk_object_list_unref (g_list_foreach (gtk_object_unref))
    nautilus_gtk_object_list_free (nautilus_gtk_object_list_unref +
g_list_free)
    nautilus_gtk_object_list_copy (nautilus_gtk_object_list_ref +
g_list_copy)

    nautilus_point_in_allocation (should be named
nautilus_gtk_allocation_<something>)
    nautilus_point_in_widget (should be named
nauitlus_gtk_widget_<something>)
    nautilus_gtk_widget_set_font (hides the style manipulation)
    nautilus_gtk_widget_set_font_by_name (gets the font too)

    nautilus_gtk_container_get_first_child (to prevent people making a
children list just to get child #1)

    nautilus_gtk_window_present (makes window show up if it's hidden,
iconified, or buried [uses a hide/show trick])

    nautilus_gtk_selection_data_copy_deep
    nautilus_gtk_selection_data_free_deep

    nautilus_pop_up_context_menu (encapsulates the boilerplate for making a
menu show up)

    nautilus_gtk_style_set_font (does the ref and unref correctly)
    nautilus_gtk_style_set_font_by_name (gets the font too)

    nautilus_gtk_pixmap_new_empty (workaround for fact that gtk_pixmap_new
won't take NULL for a pixmap, although the class can handle it fine and
allows it to be set to NULL)

    nautilus_gtk_adjustment_set_value (clamps based on page size like scroll
bars do, rather than allowing values past upper - page_size)
    nautilus_gtk_adjustment_clamp_value (nautilus_gtk_adjustment_set_value
(adjustment->value))

    a lot of additional marshal functions

----------------
nautilus-debug.h
----------------
    nautilus_stop_in_debugger (no effect if debugger isn't running, drops
into debugger if it is)
    nautilus_make_warnings_and_criticals_stop_in_debugger (we like to get a
stack trace for these if the debugger is running; only works for specific
log domains, but that could be fixed with changes to logging code)
    nautilus_get_available_file_descriptor_count (used to debug file
descriptor leaks)

---------------------------
nautilus-gnome-extensions.h
---------------------------
    lots of useful canvas related stuff (not interesting for Gtk 2.0 I
guess, but for Gnome 2.0)
    nautilus_gnome_dialog_get_button_by_index (get at the buttons created by
GnomeDialog)

-------------------------
nautilus-stock-dialogs.h
-------------------------
    nautilus_timed_wait_start/stop (pops up a dialog only if something takes
too long; includes a callback for the cancel button)
    nautilus_simple_dialog (basic modal dialog with a list of buttons)
    nautilus_info_dialog (like gnome_info_dialog_parented, but tells the
label to the message text)
    nautilus_warning_dialog (like gnome_info_dialog_parented, but tells the
label to wrap the message text)
    nautilus_error_dialog (like gnome_info_dialog_parented, but tells the
label to wrap the message text)
    nautilus_error_dialog_with_details (like nautilus_error_dialog, but has
"Details" button and gives a more-detailed message when it is pressed; so
experts can find out more about an error)
    nautilus_yes_no_dialog (like gnome_yes_no_dialog_parented, but tells the
label to wrap the message text)

-------
classes
-------
    NautilusGenerousBin (GtkBin that gives its entire allocation to the
child; useful for cases where the child has no intrinsic size, like the icon
view in Nautilus)
    NautilusPasswordDialog
    NautilusIconContainer (designed for general purpose use, but not in good
shape for that right now because file manager specifics have been added by
sloppy engineers and need to be re-factored out -- easy but will take some
time)
    NautilusList (many minor enhancements and bug fixes to GtkCList in the
form of a subclass; attempting to avoid major changes)
    NautilusCaption, NautilusCaptionTable (h boxes with titles and text; a
table of these that lines them up)

-----
other
-----
    a set of preferences UI classes
    a simple undo framework (just callbacks, no command objects)

That's a quick inventory (although it's just a snapshot of something that
keeps changing). Let me know if there's anything you particularly like and
want in Gtk 2.0.

    -- Darin