class ref name: propflag
class name: propflag
category-group: flags
layer: 0
header file: z_propflag.h
libraries: libz00.lib synopsis.
The "property flag object", or propflag_o, is a sibling of the "flag" class. It will not help you become successful at real estate, but with it you may be able to manage flag values in software better. With propflag_o you can set, clear, and check bits-flags just with flag_o. One problem a program may face is that sometimes you want to exercise control over whether a flag can be modified. Also, you may want a default value to be either TRUE (on) or FALSE (off). Perhaps you want a flag to inherit values from another flag. Or, you want to control what default values can be changed: a program sets a few default values, and allows some default values to be modifiable (say, by other programs in an stellar interprocess-based environment - maybe the flag is in shared memory!), but other default values to be fixed (at creation time). All these and more can be done by using the propflag object, via a large set of control functions, such as:
allow_modify_default()
deny_modify_default()
allow_reset()
deny_reset()
allow_override() description.
the user may designate one and only one instance of a property flag to be a "master". Once set, no other masters exist, and the right is not transferrable. Some of the rules of property flags: resizing a flag object: the property flag has a minimum size, determined by the last property flag bit. A property flag object cannot be resized smaller than this number. "Instance over-ride" of property flag values is permitted, by default. But if the flag 'no-instance-overrides' is set, it is not. These rules are patterned after human social organization - a parent dominates a child's behaviour, but the law dominates a parent's behaviour, and may over-ride what the parent does (allow / disallow / override). Each instance has these flags:
attribute flags:
value
does-child-inherit the flag?
value-changed?
the "value-changed" flag is not something that can be set;
it is an event-driven state.
permission-to-change-current-attribute flags:
can-change-value
can-change-child-inherits?
"permission-to-change-current-attribute flags" are read-only, except
for the [top-level] class flags:
permission-to-change-can-change-value?
permission-to-change-can-change-child-inherits?
There is also a "Lock" flag, which prevents any further modification
of any flag, except the "value" flag (if that flag is designated
changeable):
more-changes-allowed?
Each flag has these default values:
current value 0
default value 0
child-inherits? 0
child-inherits-default-val? 0
value-changed? 0
can-be-reset? 1
permission-to-modify-can-reset? 1
can-change-child-inherits? 1
perm.--change--change-child-inherits? 1
more-changes-allowed? 1
member functions (primary)
allow_inherit_from_default()examples.
SIGNATURE: int allow_inherit_from_default (size_t)
deny_inherit_from_default()
SIGNATURE: int deny_inherit_from_default (size_t)
allow_modify_default()
SIGNATURE: int allow_modify_default (size_t)
deny_modify_default()
SIGNATURE: int deny_modify_default (size_t)
allow_reset()
SIGNATURE: int allow_reset (size_t)
deny_reset()
SIGNATURE: int deny_reset (size_t)
allow_permission_to_ctl_reset()
SIGNATURE: int allow_permission_to_ctl_reset (size_t)
DESCRIPTION:
this will turn the flag on, if done in the master class flag object, and if further changes are allowed, and the flag has been turned off earlier. this is the only case when this routine actually does something. if the flag is already set, nothing is done, and this routine is basically a no-op. if called on the master object when changes cannot be done any more, or on a child object when the parent has revoked this permission, it is treated as an error and -1 is returned.
deny_permission_to_ctl_reset()
SIGNATURE: int deny_permission_to_ctl_reset (size_t)
DESCRIPTION:
an instance can deny its children further changes of the ability to reset a flag. however, it cannot grant it if the parent says its children cannot have permission to reset.
allow_inherit()
SIGNATURE: int allow_inherit (size_t)
deny_inherit()
SIGNATURE: int deny_inherit (size_t)
allow_modify_inherit()
SIGNATURE: int allow_modify_inherit (size_t)
deny_modify_inherit()
SIGNATURE: int deny_modify_inherit (size_t)
allow_modify_ctl_inherit()
SIGNATURE: int allow_modify_ctl_inherit (size_t)
deny_modify_ctl_inherit()
SIGNATURE: int deny_modify_ctl_inherit (size_t)
allow_override()
SIGNATURE: int allow_override (size_t, boolean)
add_classflag_range()
SIGNATURE: int add_classflag_range (size_t, size_t)
is_set()
SIGNATURE: boolean is_set (size_t)
is_default_set()
SIGNATURE: boolean is_default_set (size_t)
can_modify_default()
SIGNATURE: boolean can_modify_default (size_t)
can_be_reset()
SIGNATURE: boolean can_be_reset (size_t)
can_ctl_reset()
SIGNATURE: boolean can_ctl_reset (size_t)
does_inherit()
SIGNATURE: boolean does_inherit (size_t)
inherit_from_default()
SIGNATURE: boolean inherit_from_default (size_t)
can_ctl_inherit()
SIGNATURE: boolean can_ctl_inherit (size_t)
DESCRIPTION: this flag tells if the instance can change the flag's inheritance factor
can_modify_ctl_inherit()
SIGNATURE: boolean can_modify_ctl_inherit (size_t)
was_modified()
SIGNATURE: boolean was_modified (size_t)
DESCRIPTION: this subroutine is different from "is_set()"; it tells if the 'is-flag-set'? flag was set, not if the current flag value is "on"
EXAMPLE 1:
here's a completely restricted flag:
class sets the default value;say that bit '5' is to be configured this way; the code would be:
class sez instances must take this default value;
class sez instances cannot change this value;
class puts a lock on changing the default class value.
propflag_o pf ("some_class");
pf.set (5);
pf.allow_inherit (5);
pf.deny_reset (5);
pf.deny_permission_to_ctl_reset (5);
now, all 'first-generation' instances of flags for class
lass' will always have bit 5 default value on, and the
flag cannot be turned off. but 'second-generation' flags can
have the inheritance rules shut off by the first-generation
parent, and thus they can set up their own rule-set.
EXAMPLE 2:
here's a flag restricted to taking the default from the class:
class sets the default value; - class sez instances must take this default value; - class puts a lock on changing the default class value.this example does everything the first one does except put a clamp on changing the value, which actually gives lots of freedom. limitations.
one foreseeable extension is to have dynamic property flags; if the master changes the default value, the new value might percolate to all the children. this needs a lot more thought bugs.
incomplete: the '=' operator is completely untested history.
Sun 05/15/1994: created
Sun 05/22/1994: template code scrapped
Mon 05/23/1994: bulk of code hammered out and tested
Sat 05/28/1994: need change - class instance to have NULL parent pointer
Tue 05/31/1994: many routines made inline
Fri 07/28/1995: debate names for this object: valuflag, cloneflag, ..
Tue 10/03/1995: renamed again, 'classflag' -> 'propflag'; start overhaul
Sat 12/06/1997: compiled by g++ 2.7.2.3; back in business
Thu 05/30/2002: new #define naming conventions ("zos_", "zcc_")