Re: I need informations about the PropDescription flags

[Lars Clausen <lars raeder dk>]

On Thu, 2005-10-06 at 17:13 +0200, Jonathan CHABOISSIER wrote:
> Hi everybody !
>
> My current work is to program objects for Dia.
>
> Many of my objects properties are not saved in the dia defaults file
> as I would like. Thus, when I modify the object and restart the
> program, it always makes memory errors because of not allocated
> variables and so NULL pointer. I do not want to check every where if
> my structures are different from what they should be !
[...]
> The way properties are saved and loaded from Dia Defaults file depends
> on the PropDescription.flags, which can be :
>
> #define PROP_FLAG_VISIBLE   0x0001
> #define PROP_FLAG_DONT_SAVE 0x0002
> #define PROP_FLAG_DONT_MERGE 0x0004 /* in case group properties are
> edited */
> #define PROP_FLAG_NO_DEFAULTS 0x0008 /* don't edit this in defaults
> dlg. */
> #define PROP_FLAG_LOAD_ONLY 0x0010 /* for loading old formats */
> #define PROP_FLAG_STANDARD 0x0020 /* One of the default toolbox props
> */
> #define PROP_FLAG_MULTIVALUE 0x0040 /* Multiple values for prop in
> group */
> #define PROP_FLAG_WIDGET_ONLY 0x0080 /* only cosmetic property, no
> data */
> #define PROP_FLAG_OPTIONAL 0x0100 /* don't complain if it does not
> exist */
>
> Could you explain me with more details how which flag change the way
> my properties are saved and loaded from the default dia file ?
>
> For example, I do not really understand the differences between
> PROP_FLAG_DONT_SAVE and PROP_FLAG_LOAD_ONLY, between
> PROP_FLAG_DONT_MERGE and PROP_FLAG_MULTIVALUE ...

PROP_FLAG_MULTIVALUE and PROP_FLAG_DONT_MERGE are both only relevant in
group properties (or in multi-object properties when that is
implemented) and are more complex than I want to go into here.

PROP_FLAG_LOAD_ONLY means the property is outdated and will only be used
while loading the object and converting it to whatever new format.

PROP_FLAG_VISIBLE determines if it is shown in the properties dialog at
all.  The position property, for instance, is not shown at all
currently.

PROP_FLAG_DONT_SAVE says that the property should not be stored
automatically when using the object_save_using_properties, but will
instead be handled manually by the objects own load/save functions.  Not
to be used without a very good reason.

PROP_FLAG_NO_DEFAULTS determines whether the property will be editable
in the defaults dialogs (double-clicking the icon).  I believe this is
the flag you want.

PROP_FLAG_STANDARD means that the property is taken from the special
selectors in the toolbox, like line width, foreground color etc, rather
than from object defaults.

PROP_FLAG_WIDGET_ONLY means there is no data to store for this property.
It is used for instance for the frame property.

PROP_FLAG_OPTIONAL means that old versions of the object may not have
the property saved, and that should not be considered an error, or (less
nice) that the property is not always saved, and so lack of it means it
will be assigned a default value.  This should only be used when adding
new properties to an object that people may already have saved some of.

> I think it is certainly very logic to the ones who created Dia, but
> for me all the flags are not very meanfull and this despite the little
> comments. Could you even give an example for each one ? And to help
> could you tell me which flags I should use to always give to my
> properties the values I defined in the _create function ?

Probably PROP_FLAG_NO_DEFAULTS, but you should consider whether you want
to use that or just allow the user to edit the defaults in the defaults
dialog.  The latter way avoids hardcoding.

Hope this helps, 
-Lars

-- 
Lars Clausen <lars raeder dk>