timj's API todo

[Tim Janik <timj gtk org>]

hi all,

i'm currently cleaning up my gtk/gdk API todos, most of them
are ready for committing, however i'd like to have some
resonance before including/discarding them.
a bunch of these functions are simple convenience variants
that take just one widget arg so they can be used esily
as signal handlers:

void   gtk_scrolled_window_set_corner_widget (GtkScrolledWindow *scrolled_window,
                                              GtkWidget         *widget);
set a widget to be displayed in the corner of of the two scrollbars for
scrolled windows that have GTK_POLICY_ALWAYS for both dimensions.

void       gtk_window_showraise          (GtkWidget             *widget);

convenience function for showing a GtkWindow and then raising its window.
probably superceeded by gtk_window_present(), however that doesn't also
raise the window (especially for not _NET compliant window managers).

void       gtk_toplevel_hide             (GtkWidget             *widget);
fetch the widget's toplevel and hide that (e.g. for connections
to Close button ::clicked)

void       gtk_toplevel_activate_default (GtkWidget             *widget);
fetch the widget's toplevel and invoke gtk_window_activate_default() on that,
i mostly use that for gtkentry ::activate connections, so probably
superceeded by gtk_entry_set_activates_default().

void       gtk_idle_show_widget          (GtkWidget             *widget);
show widget from the next idle handler, mostly used to show widgets from
a callback of a window that is about to be popped down. the advantage
here is that the old, about-to-be-destroyed window won't get in they way
for the new window wrg window placement.

void       gtk_idle_unparent             (GtkWidget             *widget);
container_remove widget from the next idle handler, mostly used as a bug
workaround for 1.2.8 dnd bugs, i wonder if people would have use of that
beyond that (the bug shouldn't be present in 1.3 anymore).

gboolean gdk_window_translate           (GdkWindow      *src_window,
                                         GdkWindow      *dest_window,
                                         gint           *x,
                                         gint           *y);
XTranslateCoords wrapper to get src_widnow coordinates, relative to
dest_window.

void       gtk_last_event_coords         (gint                  *x_root,
                                          gint                  *y_root);
retrives root window x/y coordinates from the last (currently processed)
event. mostly usefull in dnd callbacks (and since root window x/y can't
be generically fetched from GtkEventAny).

void       gtk_last_event_widget_coords  (GtkWidget             *widget,
                                          gint                  *x,
                                          gint                  *y);
retrive gtk_last_event_coords() relative to widget->window, uses
gdk_window_translate().

void       gtk_widget_make_sensitive     (GtkWidget             *widget);
void       gtk_widget_make_insensitive   (GtkWidget             *widget);
sensitivity setters suitable for signal connections (quite frequently needed
in config dialogs).

void       gtk_clist_moveto_selection    (GtkCList              *clist);
assures that the clist selection stays visible (required if the
clist selection is changed programatically, not due to user input).

gpointer   gtk_clist_get_selection_data  (GtkCList              *clist,
                                          guint                  index);
returns gtk_clist_get_row_data() for the nth selected item of a clist.

i'm not sure we really want to add the clist variants, hopefully jrb's
widget will fully superceede clist in the final version.


/* --- Gtk+ Kennel --- */
typedef enum
{
  GTK_KENNEL_TO_MINIMUM = 1,
  GTK_KENNEL_TO_MAXIMUM = 2,
  GTK_KENNEL_TO_USIZE   = 3,
  GTK_KENNEL_TO_WIDGET  = 4
} GtkKennelType;
typedef    struct _GtkKennel              GtkKennel;
GtkKennel* gtk_kennel_new                (GtkKennelType          width_constrain,
                                          GtkKennelType          height_constrain);
void       gtk_kennel_configure          (GtkKennel             *kennel,
                                          GtkKennelType          width_constrain,
                                          GtkKennelType          height_constrain);
GtkKennel* gtk_kennel_ref                (GtkKennel             *kennel);
void       gtk_kennel_unref              (GtkKennel             *kennel);
void       gtk_kennel_add                (GtkKennel             *kennel,
                                          GtkWidget             *widget);
void       gtk_kennel_remove             (GtkKennel             *kennel,
                                          GtkWidget             *widget);
void       gtk_kennel_resize             (GtkKennel             *kennel,
                                          guint                  width,
                                          guint                  height);
void       gtk_kennel_set_size_template  (GtkKennel             *kennel,
                                          GtkWidget             *widget);

ultimately, GtkKennel will be made a GObject, so ref/unref vanish
from the above API. a kennel is used to constrain the size of an
arbitrary set of widgets to the minimum/maximum size of the
widgets in the set, to a specified usize or to the size of another
widget.

---
ciaoTJ