GPL_bin_fullset/NaturalDocs/Modules/NaturalDocs/Menu/Entry.pm

   1 ###############################################################################
   2 #
   3 #   Package: NaturalDocs::Menu::Entry
   4 #
   5 ###############################################################################
   6 #
   7 #   A class representing an entry in the menu.
   8 #
   9 ###############################################################################
  10
  11 # This file is part of Natural Docs, which is Copyright © 2003-2010 Greg Valure
  12 # Natural Docs is licensed under version 3 of the GNU Affero General Public License (AGPL)
  13 # Refer to License.txt for the complete details
  14
  15 use strict;
  16 use integer;
  17
  18 package NaturalDocs::Menu::Entry;
  19
  20
  21 ###############################################################################
  22 # Group: Implementation
  23
  24 #
  25 #   Constants: Members
  26 #
  27 #   The object is implemented as a blessed arrayref with the indexes below.
  28 #
  29 #       TYPE      - The <MenuEntryType>
  30 #       TITLE     - The title of the entry.
  31 #       TARGET  - The target of the entry.  If the type is <MENU_FILE>, it will be the source <FileName>.  If the type is
  32 #                       <MENU_LINK>, it will be the URL.  If the type is <MENU_GROUP>, it will be an arrayref of
  33 #                       <NaturalDocs::Menu::Entry> objects representing the group's content.  If the type is <MENU_INDEX>, it will be
  34 #                       a <TopicType>.
  35 #       FLAGS    - Any <Menu Entry Flags> that apply.
  36 #
  37 use constant TYPE => 0;
  38 use constant TITLE => 1;
  39 use constant TARGET => 2;
  40 use constant FLAGS => 3;
  41 # DEPENDENCY: New() depends on the order of these constants.
  42
  43
  44 ###############################################################################
  45 # Group: Functions
  46
  47 #
  48 #   Function: New
  49 #
  50 #   Creates and returns a new object.
  51 #
  52 #   Parameters:
  53 #
  54 #       type     - The <MenuEntryType>.
  55 #       title      - The title of the entry.
  56 #       target   - The target of the entry, if applicable.  If the type is <MENU_FILE>, use the source <FileName>.  If the type is
  57 #                     <MENU_LINK>, use the URL.  If the type is <MENU_INDEX>, use the <TopicType>.  Otherwise set it to undef.
  58 #       flags     - Any <Menu Entry Flags> that apply.
  59 #
  60 sub New #(type, title, target, flags)
  61     {
  62     # DEPENDENCY: This gode depends on the order of the constants.
  63
  64     my $package = shift;
  65
  66     my $object = [ @_ ];
  67     bless $object, $package;
  68
  69     if ($object->[TYPE] == ::MENU_GROUP())
  70         {  $object->[TARGET] = [ ];  };
  71     if (!defined $object->[FLAGS])
  72         {  $object->[FLAGS] = 0;  };
  73
  74     return $object;
  75     };
  76
  77
  78 #   Function: Type
  79 #   Returns the <MenuEntryType>.
  80 sub Type
  81     {  return $_[0]->[TYPE];  };
  82
  83 #   Function: Title
  84 #   Returns the title of the entry.
  85 sub Title
  86     {  return $_[0]->[TITLE];  };
  87
  88 # Function: SetTitle
  89 # Replaces the entry's title.
  90 sub SetTitle #(title)
  91     {  $_[0]->[TITLE] = $_[1];  };
  92
  93 #
  94 #   Function: Target
  95 #
  96 #   Returns the target of the entry, if applicable.  If the type is <MENU_FILE>, it returns the source <FileName>.  If the type is
  97 #   <MENU_LINK>, it returns the URL.  If the type is <MENU_INDEX>, it returns the <TopicType>.  Otherwise it returns undef.
  98 #
  99 sub Target
 100     {
 101     my $self = shift;
 102
 103     # Group entries are the only time when target won't be undef when it should be.
 104     if ($self->Type() == ::MENU_GROUP())
 105         {  return undef;  }
 106     else
 107         {  return $self->[TARGET];  };
 108     };
 109
 110 # Function: SetTarget
 111 # Replaces the entry's target.
 112 sub SetTarget #(target)
 113     {  $_[0]->[TARGET] = $_[1];  };
 114
 115 #   Function: Flags
 116 #   Returns the <Menu Entry Flags>.
 117 sub Flags
 118     {  return $_[0]->[FLAGS];  };
 119
 120 # Function: SetFlags
 121 # Replaces the <Menu Entry Flags>.
 122 sub SetFlags #(flags)
 123     {  $_[0]->[FLAGS] = $_[1];  };
 124
 125
 126
 127 ###############################################################################
 128 # Group: Group Functions
 129 #
 130 #   All of these functions assume the type is <MENU_GROUP>.  Do *not* call any of these without checking <Type()> first.
 131
 132
 133 #
 134 #   Function: GroupContent
 135 #
 136 #   Returns an arrayref of <NaturalDocs::Menu::Entry> objects representing the contents of the
 137 #   group, or undef otherwise.  This arrayref will always exist for <MENU_GROUP>'s and can be changed.
 138 #
 139 sub GroupContent
 140     {
 141     return $_[0]->[TARGET];
 142     };
 143
 144
 145 #
 146 #   Function: GroupIsEmpty
 147 #
 148 #   If the type is <MENU_GROUP>, returns whether the group is empty.
 149 #
 150 sub GroupIsEmpty
 151     {
 152     my $self = shift;
 153     return (scalar @{$self->GroupContent()} > 0);
 154     };
 155
 156
 157 #
 158 #   Function: PushToGroup
 159 #
 160 #   Pushes the entry to the end of the group content.
 161 #
 162 sub PushToGroup #(entry)
 163     {
 164     my ($self, $entry) = @_;
 165     push @{$self->GroupContent()}, $entry;
 166     };
 167
 168
 169 #
 170 #   Function: DeleteFromGroup
 171 #
 172 #   Deletes an entry from the group content by index.
 173 #
 174 sub DeleteFromGroup #(index)
 175     {
 176     my ($self, $index) = @_;
 177
 178     my $groupContent = $self->GroupContent();
 179
 180     splice( @$groupContent, $index, 1 );
 181     };
 182
 183
 184 #
 185 #   Function: MarkEndOfOriginal
 186 #
 187 #   If the group doesn't already have one, adds a <MENU_ENDOFORIGINAL> entry to the end and sets the
 188 #   <MENU_GROUP_HASENDOFORIGINAL> flag.
 189 #
 190 sub MarkEndOfOriginal
 191     {
 192     my $self = shift;
 193
 194     if (($self->Flags() & ::MENU_GROUP_HASENDOFORIGINAL()) == 0)
 195         {
 196         $self->PushToGroup( NaturalDocs::Menu::Entry->New(::MENU_ENDOFORIGINAL(), undef, undef, undef) );
 197         $self->SetFlags( $self->Flags() | ::MENU_GROUP_HASENDOFORIGINAL() );
 198         };
 199     };
 200
 201
 202 1;