{
* UView.pas
*
* Classes that encapsulate and provide information about "view items" that are
* displayed in the user interface, e.g.. routines, categories and the welcome
* page.
*
* v0.1 of 30 Jan 2005 - Original version.
* v0.2 of 18 Feb 2005 - Deleted unused TViewItem constructor.
* v0.3 of 19 Feb 2005 - Refactoring: TViewItem.IsEqual method now calls new
* IsEqual methods of TRoutine and TCategory objects
* rather than comparing names explicitly.
* v0.4 of 22 Feb 2005 - Localised string literals.
* v1.0 of 24 May 2006 - Improved and corrected comments.
* - Removed unused unit references.
* v1.1 of 04 Feb 2007 - Removed TDetailView class. We now use a combination of
* the Query global object and the TViewItem class to
* provide the same information.
* v1.2 of 16 May 2009 - Made private sections in both classes strict.
* - Removed Uncategorised view type
* - Added view types for alphabetic and snippet kind
* sections.
* - Refactored some code.
*
*
* ***** BEGIN LICENSE BLOCK *****
*
* Version: MPL 1.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with the
* License. You may obtain a copy of the License at http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
* the specific language governing rights and limitations under the License.
*
* The Original Code is UView.pas
*
* The Initial Developer of the Original Code is Peter Johnson
* (http://www.delphidabbler.com/).
*
* Portions created by the Initial Developer are Copyright (C) 2005-2009 Peter
* Johnson. All Rights Reserved.
*
* ***** END LICENSE BLOCK *****
}
unit UView;
interface
uses
// Delphi
Contnrs,
// Project
UAlphabet, USnippetKindInfo, USnippets;
type
{
TViewKind:
Various kinds of item that can be displayed in GUI.
}
TViewKind = (
vkNone, // view kind not defined
vkWelcome, // welcome page
vkRoutine, // information about a routine
vkCategory, // information about a category
vkSnipKind, // information about a kind of snippet
vkAlphabet // information about snippets beginning with a letter
);
{
TViewItem:
Encapsulates and provides information about "view items" that are displayed
in the overview pane of the GUI.
}
TViewItem = class(TObject)
strict private
fData: TObject;
{Object that provides additional information about a view item, depending
on its kind}
fKind: TViewKind;
{Kind of view item}
function GetDescription: string;
{Read accessor for Description property.
@return Description.
}
function GetRoutine: TRoutine;
{Read access for Routine property. Kind must be vkRoutine.
@return Data object describing routine.
}
function GetCategory: TCategory;
{Read access for Category property. Kind must be vkCategory.
@return Data object describing category.
}
function GetAlphChar: TLetter;
{Read access for AlphaChar property. Kind must be vkSnipKind.
@return Data object describing alphabetic section.
}
function GetSnippetKind: TSnippetKindInfo;
{Read access for SnippetKind property. Kind must be vkSnipKind.
@return Data object describing snippet kind section.
}
public
constructor Create; overload;
{Class constructor. Creates a view item of kind vkNone.
}
constructor Create(const Kind: TViewKind; const Data: TObject = nil);
overload;
{Class constructor. Creates a view item of a specified kind with extra
information.
@param Kind [in] Kind of view item to create.
@param Data [in] Object providing extra information. Object type depends
on Kind and must be as follows:
+ vkRoutine => TRoutine
+ vkCategory => TCategory
+ vkSnipKind => TSnippetKindInfo
+ vkAlphabet => TLetter
+ vkNone or vkWelcome => nil
}
constructor Create(const ViewItem: TViewItem); overload;
{Class constructor. Creates a view item that is a clone of another view
item.
@param ViewItem [in] View item to be cloned.
}
constructor Create(const Routine: TRoutine); overload;
{Class constructor. Creates a view item representing a routine.
@param Routine [in] Routine to be represented.
}
constructor Create(const SnippetKind: TSnippetKindInfo); overload;
{Class constructor. Creates a view item representing a snippet kind.
@param SnippetKind [in] Snippet kind to be represented.
}
constructor Create(const Letter: TLetter); overload;
{Class constructor. Creates a view item representing a alphabetic letter.
@param Letter [in] Letter to be represented.
}
procedure Assign(const ViewItem: TViewItem);
{Sets this view item to have same properties as another view item.
@param ViewItem [in] Item we are copying. A nil view item implies a Kind
of vkNone.
}
function IsEqual(const ViewItem: TViewItem): Boolean;
{Checks if this view item is the same as another view item.
@param ViewItem [in] View item being testing for equality.
@return True if view items are same, false otherwise.
}
property Kind: TViewKind read fKind;
{Kind of view item}
property Description: string read GetDescription;
{Description of view item}
property Category: TCategory read GetCategory;
{Information about category represented by view item. Only valid when
Kind = vkCategory}
property Routine: TRoutine read GetRoutine;
{Information about routine represented by view item. Only valid when
Kind = vkRoutine}
property AlphaChar: TLetter read GetAlphChar;
{Information about an alphabetic character represented by view item. Only
valid when Kind = vkAlphabet}
property SnippetKind: TSnippetKindInfo read GetSnippetKind;
{Information about a snippet kind represented by a view item. Only valid
when Kind = vkSnippetKind}
end;
{
TViewItemList:
Implements a list of TViewItem objects.
}
TViewItemList = class(TObject)
strict private
fList: TObjectList;
{The list of view items}
function GetCount: Integer;
{Read accessor for Count property.
@return Number of items in list.
}
function GetItem(Idx: Integer): TViewItem;
{Read accessor for Items[] property.
@param Idx [in] Index of desired view item in list.
@return View item at given index in list.
}
public
constructor Create;
{Class constructor. Sets up list.
}
destructor Destroy; override;
{Class destructor. Tears down object.
}
procedure Clear;
{Clears the list without freeing items in it.
}
function Add(const ViewItem: TViewItem): Integer;
{Adds new view item to list.
@param ViewItem [in] View item to add to list.
@return Index of new item in list.
}
property Items[Idx: Integer]: TViewItem read GetItem; default;
{List of view items}
property Count: Integer read GetCount;
{Number of view items in list}
end;
implementation
uses
// Delphi
SysUtils;
{ TViewItem }
procedure TViewItem.Assign(const ViewItem: TViewItem);
{Sets this view item to have same properties as another view item.
@param ViewItem [in] Item we are copying. A nil view item implies a Kind of
vkNone.
}
begin
if Assigned(ViewItem) then
begin
// New view item not nil: copy it
Self.fKind := ViewItem.fKind;
Self.fData := ViewItem.fData;
end
else
begin
// New view item nil: make a vkNone item
Self.fKind := vkNone;
Self.fData := nil;
end;
end;
constructor TViewItem.Create;
{Class constructor. Creates a view item of kind vkNone.
}
begin
inherited Create;
fKind := vkNone;
fData := nil;
end;
constructor TViewItem.Create(const Kind: TViewKind; const Data: TObject);
{Class constructor. Creates a view item of a specified kind with extra
information.
@param Kind [in] Kind of view item to create.
@param Data [in] Object providing extra information. Object type depends on
Kind and must be as follows:
+ vkRoutine => TRoutine
+ vkCategory => TCategory
+ vkSnipKind => TSnippetKindInfo
+ vkAlphabet => TLetter
+ vkNone or vkWelcome => nil
}
begin
Assert(
( (Kind in [vkNone, vkWelcome]) and not Assigned(Data) )
or ( (Kind = vkRoutine) and Assigned(Data) and (Data is TRoutine) )
or ( (Kind = vkCategory) and Assigned(Data) and (Data is TCategory) )
or ( (Kind = vkSnipKind) and Assigned(Data) and (Data is TSnippetKindInfo) )
or ( (Kind = vkAlphabet) and Assigned(Data) and (Data is TLetter) ),
ClassName + '.Create: Invalid parameters'
);
inherited Create;
// Record kind and data object
fKind := Kind;
fData := Data;
end;
constructor TViewItem.Create(const ViewItem: TViewItem);
{Class constructor. Creates a view item that is a clone of another view item.
@param ViewItem [in] View item to be cloned.
}
begin
inherited Create;
Assign(ViewItem);
end;
constructor TViewItem.Create(const SnippetKind: TSnippetKindInfo);
{Class constructor. Creates a view item representing a snippet kind.
@param SnippetKind [in] Snippet kind to be represented.
}
begin
Create(vkSnipKind, SnippetKind);
end;
constructor TViewItem.Create(const Routine: TRoutine);
{Class constructor. Creates a view item representing a routine.
@param Routine [in] Routine to be represented.
}
begin
Create(vkRoutine, Routine);
end;
constructor TViewItem.Create(const Letter: TLetter);
{Class constructor. Creates a view item representing a alphabetic letter.
@param Letter [in] Letter to be represented.
}
begin
Create(vkAlphabet, Letter);
end;
function TViewItem.GetAlphChar: TLetter;
{Read access for AlphaChar property. Kind must be vkSnipKind.
@return Data object describing alphabetic section.
}
begin
Assert(fKind = vkAlphabet,
ClassName + '.GetAlphaChar: Kind is not vkAlphabet');
Result := fData as TLetter;
end;
function TViewItem.GetCategory: TCategory;
{Read access for Category property. Kind must be vkCategory.
@return Data object describing category.
}
begin
Assert(fKind = vkCategory,
ClassName + '.GetCategory: Kind is not vkCategory');
Result := fData as TCategory;
end;
function TViewItem.GetDescription: string;
{Read accessor for Description property.
@return Description.
}
resourcestring
// view item descriptions
sNoneDesc = 'Empty item';
sWelcomeDesc = 'Welcome page';
sUnknownDesc = 'Unknown view item type';
begin
// Description depends on kind of view item
case fKind of
vkNone: Result := sNoneDesc;
vkWelcome: Result := sWelcomeDesc;
vkRoutine: Result := Routine.Name;
vkCategory: Result := Category.Description;
vkAlphabet: Result := AlphaChar.Letter;
vkSnipKind: Result := SnippetKind.Description;
else Result := sUnknownDesc;
end;
end;
function TViewItem.GetRoutine: TRoutine;
{Read access for Routine property. Kind must be vkRoutine.
@return Data object describing routine.
}
begin
Assert(fKind = vkRoutine, ClassName + '.GetRoutine: Kind is not vkRoutine');
Result := fData as TRoutine;
end;
function TViewItem.GetSnippetKind: TSnippetKindInfo;
{Read access for SnippetKind property. Kind must be vkSnipKind.
@return Data object describing snippet kind section.
}
begin
Assert(fKind = vkSnipKind,
ClassName + '.GetSnippetKind: Kind is not vkSnipKind');
Result := fData as TSnippetKindInfo;
end;
function TViewItem.IsEqual(const ViewItem: TViewItem): Boolean;
{Checks if this view item is the same as another view item.
@param ViewItem [in] View item being testing for equality.
@return True if view items are same, false otherwise.
}
begin
// Kinds of objects must be same for equality
Result := (Self.fKind = ViewItem.fKind);
// If kind has a data object, they must also be "same"
if Result then
case fKind of
vkRoutine: Result := Routine.IsEqual(ViewItem.Routine);
vkCategory: Result := Category.IsEqual(ViewItem.Category);
vkAlphabet: Result := AlphaChar.Letter = ViewItem.AlphaChar.Letter;
vkSnipKind: Result := SnippetKind.Kind = ViewItem.SnippetKind.Kind;
end;
end;
{ TViewItemList }
function TViewItemList.Add(const ViewItem: TViewItem): Integer;
{Adds new view item to list.
@param ViewItem [in] View item to add to list.
@return Index of new item in list.
}
begin
Result := fList.Add(ViewItem);
end;
procedure TViewItemList.Clear;
{Clears the list without freeing items in it.
}
begin
fList.Clear;
end;
constructor TViewItemList.Create;
{Class constructor. Sets up list.
}
begin
inherited;
// Create list that doesn't own the objects in it
fList := TObjectList.Create(False);
end;
destructor TViewItemList.Destroy;
{Class destructor. Tears down object.
}
begin
FreeAndNil(fList); // does not free the objects in the list
inherited;
end;
function TViewItemList.GetCount: Integer;
{Read accessor for Count property.
@return Number of items in list.
}
begin
Result := fList.Count;
end;
function TViewItemList.GetItem(Idx: Integer): TViewItem;
{Read accessor for Items[] property.
@param Idx [in] Index of desired view item in list.
@return View item at given index in list.
}
begin
Result := fList[Idx] as TViewItem;
end;
end.
