aboutsummaryrefslogtreecommitdiffstats
path: root/Game/Code
diff options
context:
space:
mode:
authork-m_schindler <k-m_schindler@b956fd51-792f-4845-bead-9b4dfca2ff2c>2008-08-15 19:31:44 +0000
committerk-m_schindler <k-m_schindler@b956fd51-792f-4845-bead-9b4dfca2ff2c>2008-08-15 19:31:44 +0000
commit2334e3930b15f0d3bcd3b754a286f36aa5157ed6 (patch)
tree87cfda8de53430ea83be2758d8e51765a8eaba94 /Game/Code
parent2deedc482d16a96bcc89dbe06d26215d26ed9644 (diff)
downloadusdx-2334e3930b15f0d3bcd3b754a286f36aa5157ed6.tar.gz
usdx-2334e3930b15f0d3bcd3b754a286f36aa5157ed6.tar.xz
usdx-2334e3930b15f0d3bcd3b754a286f36aa5157ed6.zip
comments updated, also for the use with PasDoc.
git-svn-id: svn://svn.code.sf.net/p/ultrastardx/svn/trunk@1269 b956fd51-792f-4845-bead-9b4dfca2ff2c
Diffstat (limited to 'Game/Code')
-rw-r--r--Game/Code/Classes/UPlatformMacOSX.pas193
1 files changed, 152 insertions, 41 deletions
diff --git a/Game/Code/Classes/UPlatformMacOSX.pas b/Game/Code/Classes/UPlatformMacOSX.pas
index 223908d4..1da83c9c 100644
--- a/Game/Code/Classes/UPlatformMacOSX.pas
+++ b/Game/Code/Classes/UPlatformMacOSX.pas
@@ -1,74 +1,149 @@
unit UPlatformMacOSX;
+interface
+
+{$IFDEF FPC}
+ {$MODE Delphi}
+{$ENDIF}
+
+{$I switches.inc}
+
+uses
+{ Used from Classes:
+ Classes
+ TStringList
+ TFileStream
+}
+ Classes,
+
+{ Used from UPlatform:
+ Types
+ TDirectoryEntryArray
+ Overriding parts of UPlatform:
+ Functions and Procedures
+ Init
+ DirectoryFindFiles
+ GetLogPath
+ GetGameSharedPath
+ GetGameUserPath
+}
+ UPlatform;
+
+type
{
- Note on directories (by eddie):
- We use subfolders of the application directory on tha mac, because:
- 1. Installation on the mac works as follows: Extract and copy an application
+@abstract(Provides Mac OS X specific details.)
+@lastmod(August 1, 2008)
+The UPlatformMacOSX unit takes care of setting paths to resource folders.
+
+(Note for non-Maccies: "folder" is the Mac name for directory.)
+
+ Note on the resource folders:
+ 1. Installation of an application on the mac works as follows: Extract and copy an application
and if you don't like or need the application anymore you move the folder
to the trash - and you're done.
- 2. If we would use subfolders of the home directory we would have to spread our
- files to many directories - these directories are defined by Apple, but the
- average user doesn't know them, beacuse he or she doesn't need to know them.
- But for UltraStar the user must at least know the songs directory...
-
- Creating a subfolder directly under the home directory is not acceptable.
+ 2. The use folders in the user's home directory is against Apple's guidelines
+ and strange to an average user.
+ 3. Even worse is using /usr/local/... since all lowercase folders in / are
+ not visible to an average user in the Finder, at least not without some "tricks".
- More on this from KMS aka mischi
+ The best way would be to store everything within the application bundle. However, this
+ requires USDX to offer the handling of the resources. Until this is implemented, the
+ second best solution is as follows:
- Handling of resources and folders should follow these lines.
+ According to Aple guidelines handling of resources and folders should follow these lines:
Acceptable places for files are folders named UltraStarDeluxe either in
/Library/Application Support/
or
~/Library/Application Support/
- Then
+ So
GetGameSharedPath could return
- /Library/Application Support/UltraStarDeluxe/Resources/
+ /Library/Application Support/UltraStarDeluxe/Resources/.
GetGameUserPath could return
- ~/Library/Application Support/UltraStarDeluxe/Resources/
+ ~/Library/Application Support/UltraStarDeluxe/Resources/.
+
+ Right now, only $HOME/Library/Application Support/UltraStarDeluxe/Resources
+ is used. So every user needs the complete set of files and folders.
+ Future versions may also use shared resources in
+ /Library/Application Support/UltraStarDeluxe/Resources. However, this is not
+ treated yet in the code outside this unit.
- USDX checks, whether GetGameUserPath exists. If not, USDX creates its.
- The existance of needed files is then checked and if a file is missing
+ USDX checks, whether GetGameUserPath exists. If not, USDX creates it.
+ The existence of needed files is then checked and if a file is missing
it is copied to there from within the Resources folder in the Application
bundle, which contains the default files. USDX should not delete files or
folders in Application Support/UltraStarDeluxe automatically or without
user confirmation.
}
-
-interface
-
-{$IFDEF FPC}
- {$MODE Delphi}
-{$ENDIF}
-
-{$I switches.inc}
-
-uses
- Classes,
- UPlatform;
-
-type
TPlatformMacOSX = class(TPlatform)
private
+{ GetBundlePath returns the path to the application bundle UltraStarDeluxe.app.
+}
function GetBundlePath: WideString;
+{ GetApplicationSupportPath returns the path to
+ $HOME/Library/Application Support/UltraStarDeluxe/Resources.
+}
function GetApplicationSupportPath: WideString;
+{ see the description of @link(Init). }
procedure CreateUserFolders();
public
+{ Init simply calls @link(CreateUserFolders), which in turn scans the folder
+ UltraStarDeluxe.app/Contents/Resources for all files and folders.
+ $HOME/Library/Application Support/UltraStarDeluxe/Resources is then checked
+ for their presence and missing ones are copied.
+}
procedure Init; override;
-
+{ DirectoryFindFiles returns all entries of a folder with names and booleans
+ about their type, i.e. file or directory.
+}
function DirectoryFindFiles(Dir, Filter: WideString; ReturnAllSubDirs: boolean): TDirectoryEntryArray; override;
-
+{ GetLogPath returns the path for log messages. Currently it is set to
+ $HOME/Library/Application Support/UltraStarDeluxe/Resources/Log.
+}
function GetLogPath : WideString; override;
+{ GetGameSharedPath returns the path for shared resources. Currently it is set to
+ /Library/Application Support/UltraStarDeluxe/Resources.
+ However it is not used.
+}
function GetGameSharedPath : WideString; override;
+{ GetGameUserPath returns the path for user resources. Currently it is set to
+ $HOME/Library/Application Support/UltraStarDeluxe/Resources.
+ This is where a user can add songs, themes, ....
+}
function GetGameUserPath : WideString; override;
end;
implementation
uses
+{ Used from SysUtils:
+ Types
+ TSearchRec
+ Constants
+ faAnyFile
+ Functions and Procedures
+ DirectoryExists
+ ExtractFilePath
+ FileGetAttr
+ FileExists
+ FindFirst
+ FindNext
+ FindClose
+ GetEnvironmentVariable
+}
SysUtils,
- baseunix;
+
+{ Used from BaseUnix:
+ Types
+ pdir
+ pDirent
+ Functions and Procedures
+ FPOpenDir
+ FPReadDir
+ FPCloseDir
+}
+ BaseUnix;
procedure TPlatformMacOSX.Init;
begin
@@ -77,29 +152,65 @@ end;
procedure TPlatformMacOSX.CreateUserFolders();
var
- RelativePath, BaseDir, OldBaseDir: string;
+{ }
+ RelativePath,
+{ BaseDir contains the path to the folder, where a search is performed.
+ It is set to the entries in @link(DirectoryList) one after the other.
+}
+ BaseDir,
+{ OldBaseDir contains the path to the folder, where the search started.
+ It is used to return to it, when the search is completed in all folders.
+}
+ OldBaseDir: string;
+{ This record contains the result of a file search with FindFirst or FindNext}
SearchInfo: TSearchRec;
+{ These two lists contain all folder and file names found
+ within the folder @link(BaseDir).
+}
DirectoryList, FileList: TStringList;
+{ DirectoryIsFinished contains the index of the folder in @link(DirectoryList),
+ which is the last one completely searched. Later folders are still to be
+ searched for additional files and folders.
+}
DirectoryIsFinished: longint;
counter: longint;
UserPathName: string;
+{ SourceFile and TaretFile are used to copy a file from on folder to another. }
SourceFile, TargetFile: TFileStream;
+{ FileCopyBuffer is the buffer for copying @link(SourceFile) to @link(TargetFile).
+ Its size (4096) has been choosen with little testing. A smaller size makes
+ copying slower. A larger size may make copying large files faster.
+}
FileCopyBuffer: array [1..4096] of byte;
+{ NumberOfBytes is the number of bytes read from @link(SourceFile) }
NumberOfBytes: integer;
const
+{ This string is used to construct the @link(UserPathName) }
PathName: string = '/Library/Application Support/UltraStarDeluxe/Resources';
begin
+{ Get the current folder and save it in OldBaseDir for returning to it, when
+ finished.
+}
getdir (0, OldBaseDir);
+{ UltraStarDeluxe.app/Contents/Resources contains all the default files and
+ folders.
+}
BaseDir := OldBaseDir + '/UltraStarDeluxe.app/Contents/Resources';
chdir (BaseDir);
+{ Right now, only $HOME/Library/Application Support/UltraStarDeluxe/Resources
+ is used.
+}
UserPathName := GetEnvironmentVariable('HOME') + PathName;
DirectoryIsFinished := 0;
DirectoryList := TStringList.Create();
FileList := TStringList.Create();
DirectoryList.Add('.');
+
+{ create the folder and file lists }
repeat
+
RelativePath := DirectoryList[DirectoryIsFinished];
chdir (BaseDir + '/' + RelativePath);
if (FindFirst('*', faAnyFile, SearchInfo) = 0) then
@@ -118,6 +229,7 @@ begin
DirectoryIsFinished := succ(DirectoryIsFinished);
until (DirectoryIsFinished = DirectoryList.Count);
+{ create missing folders }
if not DirectoryExists(UserPathName) then
mkdir (UserPathName);
@@ -126,6 +238,7 @@ begin
mkdir (UserPathName + '/' + DirectoryList[counter]);
DirectoryList.Free();
+{ copy missing files }
for counter := 0 to Filelist.Count-1 do
if not FileExists(UserPathName + '/' + Filelist[counter]) then
begin
@@ -140,13 +253,14 @@ begin
end;
FileList.Free();
+{ go back to the initial folder }
chdir (OldBaseDir);
end;
-// Mac applications are packaged in directories.
-// We have to cut the last two directories
-// to get the application directory.
-
+{ Mac applications are packaged in folders.
+ We have to cut the last two folders
+ to get the application folder.
+}
function TPlatformMacOSX.GetBundlePath: WideString;
var
i, pos : integer;
@@ -171,19 +285,16 @@ end;
function TPlatformMacOSX.GetLogPath: WideString;
begin
- // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
Result := GetApplicationSupportPath + 'Logs';
end;
function TPlatformMacOSX.GetGameSharedPath: WideString;
begin
- // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
Result := GetApplicationSupportPath;
end;
function TPlatformMacOSX.GetGameUserPath: WideString;
begin
- // eddie: Please read the note at the top of this file, why we use the application directory and not the user directory.
Result := GetApplicationSupportPath;
end;