Re: can_change_screen property for GtkWindow

[Tim Janik <timj gtk org>]

On Wed, 2 Oct 2002, Owen Taylor wrote:

>  * The "foo" "foo_set" convention for properties is already 
>    well established, and it's easy for GUI builders to
>    make reasonable GUI's for it.
> 
>    So, it made sense to me to have:
> 
>     can_change_screen
>     can_change_screen_set
>    
>    Properties as the property interface. get/notify
>    can_change_screen() could reasonably either be:
> 
>     - value set
>     - effective value
>   
>    I decided to go with the value set because:
> 
>     - I don't know any particular reason to monitor the
>       effective value (when this window becomes possible to
>       move between screens, I'll move it?)
>     - notifying the effective value is somewhat code-bloaty
>       and expensive.

it doesn't matter much whether you consider monitoring of this special value
a common case or not. the simple rule is that properties emit change
notification once their value changes, regardless of the value's semantic.
but to provide a little bit of motivation here ;), GUI builders actually need
this to update their GUI accordingly, to record time stamps of property
changes etc...

>  * For the C API, a minimum convenient interface is
> 
>    void     gtk_window_set_can_change_screen         (GtkWindow *window,
> 						      gboolean   can_change_screen);
>    gboolean gtk_window_get_can_change_screen         (GtkWindow *window); /* effective value */
>    gboolean gtk_window_get_default_can_change_screen (void);
>    void     gtk_window_set_default_can_change_screen (gboolean   can_change_screen);
> 
>   I added:
> 
>    void     gtk_window_unset_can_change_screen       (GtkWindow *window);
> 
>   because I dislike having actions (set_can_change_screen()) that can't
>   be undone.
> 
> Are there other possible interfaces? Yes, e.g., with a special enum:
> 
>   typedef enum {
>     GTK_SCREEN_CHANGE_DEFAULT
>     GTK_SCREEN_CHANGE_IMPOSSIBLE
>     GTK_SCREEN_CHANGE_POSSIBLE
>   } GtkScreenChangeMode;
> 
>    void                gtk_window_set_screen_change_mode (GtkWindow           *window,
>                                                           GtkScreenChangeMode  mode);
>    GtkScreenChangeMode gtk_window_get_screen_change_mode (GtkWindow           *window);
>    gboolean            gtk_window_can_change_screen      (GtkWindow           *window);
> 
>    void                gtk_window_set_default_screen_change_mode  (GtkScreenChangeMode mode);
>    GtkScreenChangeMode gtk_window_get_default_screen_change_mode  (void);
> 
>   And a ::screen_change_mode property.
> 
> But think my API works fine and is less clunky.

i much prefer the tri-state API (though, that's yours also now ;) and consider
the *_set aproach clunky, if not hackish.

to extend on this for a bit, the primary reason i dislike the *_set property
approach is that introducing two distinct properties which affect each others
values when set is a bad idea in general. following the convention that one
of them is named *_set and boolean and could thusly be figured by generic
code like GUI builders or users is simply not enough. either everyone
using the property system knows and commits to this convention or it's
pretty much worthless (in terms of writing generic code for it and have
users use object properties intuitively).
so (despite other griefs i'm having with *_set properties), if you really
want to follow this route in future API design, lets at least make things
explicit (for generic code and documentation generators) by introducing:

/* returns name of a boolean property */
const gchar* g_param_spec_get_setter (GParamSpec *client_pspec);

/* returns client pspec name from a boolean setter */
const gchar* g_param_spec_get_client (GParamSpec *setter_pspec);

/* returns a boolean setter property for client_property */
GParamSpec* g_param_spec_setter (const gchar    *client_property,
                                 gboolean        default_value,
                                 GParamSpecFlags flags);

so you introduce the abpove properties as:

object_class_add_property (class,
                           g_param_spec_boolean ("screen_migratable",
                                                 _("Screen Migratable"),
                                                 _("Indicate whether a window can be moved between screen"),
                                                 FALSE, G_PARAM_READWRITE));
object_class_add_property (class,
                           g_param_spec_setter ("screen_migratable",
                                                FALSE, G_PARAM_READWRITE));

the latter is simply a shorthand for:
                                                 
object_class_add_property (class,
                           g_param_spec_boolean ("screen_migratable" "_set",
                                                 _("Screen Migratable Set"),
                                                 _("Toggle whether `screen_migratable' is set or unset"),
                                                 FALSE, G_PARAM_READWRITE));
as well as setting "screen_migratable" as client on the "screen_migratable_set"
pspec and setting "screen_migratable_set" as setter on the "screen_migratable"
pspec.

> 
> Regards,
>                                         Owen
> 

---
ciaoTJ