The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
=pod

=head1 NAME

FLTK::Preferences - Application preferences

=head1 Description

Preferences are data trees containing a root, branches and leaves.

=head1 Functions

=head2 C<deleteEntry>
X<deleteEntry>

=over

=item C<my $gone = $preferences-E<gt>deleteEntry( $entry );>X<my_gone_preferences_E_gt_deleteEntry_entry_>

Delete a group.

=for hackers xs/Preferences.xs line 203

=back

=head2 C<deleteGroup>
X<deleteGroup>

=over

=item C<my $removed = $preferences-E<gt>deleteGroup( $group );>X<my_removed_preferences_E_gt_deleteGroup_group_>

Delete a group.

=for hackers xs/Preferences.xs line 167

=back

=head2 C<destroy>
X<destroy>

=over

=item C<$preferences-E<gt>destroy( );>X<_preferences_E_gt_destroy_>

Destroy individual keys.

Destroying the base L<preferences|FLTK::Preferences> will flush changes to the
prefs file. After destroying the base, none of the depending
L<preferences|FLTK::Preferences> must be read or written.

=for hackers xs/Preferences.xs line 124

=back

=head2 C<entries>
X<entries>

=over

=item C<my $count = $preferences-E<gt>entries( );>X<my_count_preferences_E_gt_entries_>

Returns the number of entries (key/value) pairs for a group.

=for hackers xs/Preferences.xs line 179

=back

=head2 C<entry>
X<entry>

=over

=item C<my $key = $preferences-E<gt>entry( $index );>X<my_key_preferences_E_gt_entry_index_>

Returns the name of an entry. There is no guaranteed order of entry names and
C<$index> must be within the range given by
L<C<entries()>|FLTK::Preferences/"entries">.

=for hackers xs/Preferences.xs line 188

=back

=head2 C<entryExists>
X<entryExists>

=over

=item C<my $exists = $preferences-E<gt>entryExists( $entry );>X<my_exists_preferences_E_gt_entryExists_entry_>

Returns C<1>, if a group with this name exists.

=for hackers xs/Preferences.xs line 199

=back

=head2 C<flush>
X<flush>

=over

=item C<$preferences-E<gt>flush( );>X<_preferences_E_gt_flush_>

Writes all preferences to disk. This method works only with the base
L<preference|FLTK::Preferences> group.

Note: This method is rarely used as the L<preferences|FLTK::Preferences> flush
automatically when L<C<destroy( )>|FLTK::Preferences/"destroy"> is called or
when the base L<preferences|FLTK::Preferences> go out of scope.

=pod 

=for hackers xs/Preferences.xs line 262

=back

=head2 C<get>
X<get>

=over

=item C<my $value = $preferences-E<gt>get( $key, $value, $defaultValue );>X<my_value_preferences_E_gt_get_key_value_defaultValue_>

Get an entry (key/value) pair.

=for hackers xs/Preferences.xs line 224

=back

=head2 C<getUserdataPath>
X<getUserdataPath>

=over

=item C<my $path = $preferences-E<gt>getUserdataPath( );>X<my_path_preferences_E_gt_getUserdataPath_>

Creates a path that is related to the preferences file and that is usable for
application data beyond what is covered by L<Preferences|FLTK::Preferences>.

=for hackers xs/Preferences.xs line 243

=back

=head2 C<group>
X<group>

=over

=item C<my $name = $preferences-E<gt>group( $index );>X<my_name_preferences_E_gt_group_index_>

Returns the group name of the C<$index>th group. There is no guaranteed order
of group names and C<$index> must be within the range given by
L<C<groups( )>|FLTK::Preferences/"groups">.

=for hackers xs/Preferences.xs line 152

=back

=head2 C<groupExists>
X<groupExists>

=over

=item C<my $exists = $preferences-E<gt>groupExists( $group );>X<my_exists_preferences_E_gt_groupExists_group_>

Returns C<1>, if a group with this name exists.

=for hackers xs/Preferences.xs line 163

=back

=head2 C<groups>
X<groups>

=over

=item C<my $count = $preferences-E<gt>groups( );>X<my_count_preferences_E_gt_groups_>

Returns the number of groups that are contained within a group.

=for hackers xs/Preferences.xs line 143

=back

=head2 C<new>
X<new>

=over

=item C<my $tree = $preferences-E<gt>new( $root, $vendor, $application );>X<my_tree_preferences_E_gt_new_root_vendor_application_>

Creates a new L<preferences|FLTK::Preferences> object.

=over 

=item * C<$root> is a value representing either per machine
(C<FLTK::Preferences::SYSTEM>) or per user (C<FLTK::Preferences::USER>)
settings.

=item * C<vendor> is the unique identification of the author or vendor of
C<$application>.

Note: vendor must be a valid directory name.

=item * C<$application> is a vendor unique application name, for example,
C<PreferencesTest>. Multiple preferences files can be created per application.

Note: application name must be a valid file name.

=back 

=for hackers xs/Preferences.xs line 43

=item C<my $node = $preferences-E<gt>new( $parent, $group );>X<my_node_preferences_E_gt_new_parent_group_>

Creates a L<Preferences|FLTK::Preferences> node in relation to a parent node
for reading and writing

=over 

=item * C<$parent> is the base name for the group.

=item * C<$group> is a group name which may contain C</> separated group
names.

=back 

Example:

  my $colors = FLTK::Preferences->new( $prefs, 'setup/colors' );

=for hackers xs/Preferences.xs line 65

=item C<my $prefs = $preferences-E<gt>new( $path, $vendor, $application );>X<my_prefs_preferences_E_gt_new_path_vendor_application_>

Creates a L<Preferences|FLTK::Preferences> object.

=over 

=item * C<$path> is an application-supplied path.

=back 

=for hackers xs/Preferences.xs line 83

=back

=head2 C<set>
X<set>

=over

=item C<my $okay = $preferences-E<gt>set( $entry, $value );>X<my_okay_preferences_E_gt_set_entry_value_>

Set an entry (key/value) pair.

=for hackers xs/Preferences.xs line 215

=back

=head2 C<size>
X<size>

=over

=item C<my $length = $preferences-E<gt>size( $key );>X<my_length_preferences_E_gt_size_key_>

Returns the size of the value part of an entry.

=for hackers xs/Preferences.xs line 234

=back

=head1 Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

=head1 License and Legal

Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under
the terms of
L<The Artistic License 2.0|http://www.perlfoundation.org/artistic_license_2_0>.
See the F<LICENSE> file included with this distribution or
L<notes on the Artistic License 2.0|http://www.perlfoundation.org/artistic_2_0_notes>
for clarification.

When separated from the distribution, all original POD documentation is
covered by the
L<Creative Commons Attribution-Share Alike 3.0 License|http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>.
See the
L<clarification of the CCA-SA3.0|http://creativecommons.org/licenses/by-sa/3.0/us/>.


=for git $Id: Preferences.xs 7483df2 2011-04-09 05:42:22Z sanko@cpan.org $

=cut