"{ Encoding: utf8 }"

"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

"{ Package: 'stx:libview' }"

"{ NameSpace: Smalltalk }"

Dictionary subclass:#ResourcePack

	instanceVariableNames:'packsClassName packsFileName fileReadFailed superPack projectPack

		usedKeys cache superPacks'

	classVariableNames:'DebugModifications FailedToLoadPacks KeepStatisticsOnUsedKeys

		Packs LastLanguageChosen DebugResources'

	poolDictionaries:''

	category:'Interface-Internationalization'

!

!ResourcePack class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

              All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    This class supports easy customization of smalltalk code (i.e. internationalization

    and viewStyle adaption).

    ResourcePacks are class specific, meaning that every subclass of View

    and ApplicationModel has an instance of ResourcePack (instVar called 'resources')

    which is created when the first instance of the view/app is created,

    and cached in a class-instVar (so the file is only read once).

    The resourcePack consists of a mapping from strings to values, which are

    then used in labels, buttons, menus etc.

    The resourcePack initializes itself from a file found in 'resources/<className>.rs',

    where 'className' is built by the usual abbreviation mechanism (see abbrev-files).

    In addition, every resourcePack has references to one or multiple so called 'superPacks',

    which are typically shared among all classees within a package (eg. libwidg, libtool, app-package),

    and which themself usually have superpacks.

    Conditional mappings are possible, by including lines as:

        #if <expression>

        #endif

    in the resourcefile. Example:

    file 'foo.rs':

        #if Language == #de

        'abort' 'Abbruch'

        #endif

        #if Language == #fr

        'abort' 'canceller'

        #endif

    the corresponding resource-strings are accessed (from methods within the class)

    using:

        resources string:'abort'

    returning the mapped string (i.e. 'Abbruch' if the global Language is set

    to #de)..

    If no corresponding entry is found in the resources, the key is returned;

    alternatively, use:

        resources string:'foo' default:'bar'

    which returns 'bar', if no resource definition for 'foo' is found.

    Translations can also include arguments, such as:

        resources string:'really delete %1' with:fileName

    This scheme has the advantage, that you can write your programs using your

    native language strings. Later, when new languages are to be supported,

    simply create a resource file for the class and add translations for

    all those strings. (find the keys by looking at users of resource or senders

    of 'string:*').

    Notice, that the grammar of different languages may imply a reordering,

    so the above string becomes the german 'wollen Sie %1 wirklich löschen';

    so using percent-placeholders is much better than simple concatenations of

    arguments to the question.

    More languages can be added later without any change in the code, or recompilation

    or the like. Even by people without access to the source code (i.e. which only have the

    application's binary).

    Also, unsupported languages' strings are simply left unchanged - if you

    write your application in (say) english, and only plan to use it in english,

    no additional work is required (i.e you don't even need a resource file then).

    Strings for unknown languages will come in english

    (which is better than nothing or empty button labels ;-)

    Notice, that you can also translate english to english, by providing an en.rs file.

    This is sometimes useful to fix typing errors or bad syntax in the english,

    as sometimes made by the programmer, without a need to recompile or to also adjust other

    language translations.

    Finally, this scheme is also compatible to a pure enum-key based translation mechanism,

    as typically used in the C-world.

    Simple use keys as argument, and provide translations for all languages (incl. english).

    For example:

        Button label:(resources string:#BTN_FOO_LABEL)

    Summary:

        in subclasses of View and ApplicationModel, instead of writing:

                ...

                b := Button label:'press me'

                ...

        always write:

                ...

                b := Button label:(resources string:'press me')

                ...

        if your class is not a subclass of one of the above, AND you need

        resource translations, you won't inherit the resources variable

        (which is automatically initialized).

        In this case, you have to ask the ResourcePack class explicitely for

        a corresponding package:

                ResourcePack for:aClassName

        or (even better):

                ResourcePack forPackage:aPackageID

        as an example, see how the Date class gets the national names of

        week & monthnames.

    Debugging:

        in the past, it happened that strings as returned by me were modified by someone else

        (replaceAll:with:) and then lead to invalid presentation in the future.

        To detect any bad guy which writes into one of my returned strings, set the DebugModifications

        classVar to true. Then I will return ImmutableStrings which trap on writes.

    [author:]

        Claus Gittinger

"

!

examples

"

    normally, resources are found in files named after their classes sourcefile,

    or in 'resources.rs' under the package's 'resources' folder.

    For example, the FileBrowsers resources might be found in 'FBrowser.rs',

    or in the package's summary resources 'libwidg/resources/resources.rs'.

    Notice: 

        in previous older ST/X versions, there where individual resource files as per class;

        this lead to many duplicate entries and many small resource files.

        Therefore, these have been concentrated into one resource file as per package,

        which typically dispatches to a specific resource files named <lang>.rs.

        See the libwidg/resources or libview/resources folders as examples.

    For the examples below, we process resources from a constant string;

        this is NOT representative.

                                                                        [exBegin]

        |stream res|

        stream := ReadStream on:'

foo  ''the translation for foo''

#if Language == #de

bar  ''die deutsche uebersetzung von bar''

baz  ''baz hat den Wert %1''

#endif

#if Language == #fr

bar  ''bar en francaise''

baz  ''%1, c''''est baz''

#endif

'.

        res := ResourcePack new readFromResourceStream:stream in:nil.

        Transcript showCR:'baz is translated to: ' , (res string:'baz' with:'1234').

        Transcript showCR:'bar is translated to: ' , (res string:'bar').

        Transcript showCR:'foo is translated to: ' , (res string:'foo').

        Transcript showCR:'fooBar is translated to: ' , (res string:'fooBar').

                                                                        [exEnd]

    set the Language to french:

                                                                        [exBegin]

        Language := #fr

                                                                        [exEnd]

    and repeat the above.

    back to english:

                                                                        [exBegin]

        Language := #en

                                                                        [exEnd]

    back to german:

                                                                        [exBegin]

        Language := #de

                                                                        [exEnd]

"

! !

!ResourcePack class methodsFor:'initialization'!

flushCachedResourcePacks

    "forget all cached resources - needed after a style change"

    Packs := FailedToLoadPacks := nil.

    self initialize.

    "

     ResourcePack flushCachedResourcePacks

    "

    "Modified: / 21-02-2019 / 14:55:45 / Claus Gittinger"

!

initialize

    Packs isNil ifTrue:[

        Packs := WeakArray new:50.

        FailedToLoadPacks := Set new.

        KeepStatisticsOnUsedKeys := false.

        DebugModifications := Smalltalk isSmalltalkDevelopmentSystem.

    ].

    "

     ResourcePack initialize

     ResourcePack flushCachedResourcePacks.

     ApplicationModel flushAllClassResources.

     SimpleView flushAllClassResources.

     SimpleView classResources

    "

    "Modified: / 28-09-2011 / 15:53:21 / cg"

    "Modified: / 15-03-2019 / 11:05:34 / Stefan Vogel"

! !

!ResourcePack class methodsFor:'instance creation'!

addAdditionalSuperPacksForPackage:packageID to:resourcePack

    |prjDefinition|

    prjDefinition := ProjectDefinition definitionClassForPackage:packageID.

    prjDefinition notNil ifTrue:[

        (prjDefinition additionalClassResources ? #()) do:[:each |

            resourcePack addSuperPack:each

        ]

    ].

!

for:aClass

    "get the full resource definitions for aClass (i.e. with super packs).

     Also leave the resulting pack in the cache for faster access next time."

    ^ self for:aClass cached:false

    "

     ResourcePack for:TextView

     ResourcePack for:CodeView

     ResourcePack for:Workspace

     ResourcePack for:View

     ResourcePack for:ErrorLogger

     ResourcePack for:NewLauncher

     ResourcePack for:SmallSense::SettingsAppl

     Workspace classResources

    "

    "Modified: / 18-09-2006 / 19:02:57 / cg"

!

for:aClass cached:cached

    "get the full resource definitions for aClass (i.e. with super packs).

     Also optionally leave the resulting pack in the cache for faster access next time."

    ^ self forPackage:(aClass package) cached:cached.

"/    |nm pack rsrcDir baseName|

"/

"/    nm := aClass resourcePackName.

"/    cached ifTrue:[

"/        pack := self searchCacheFor:nm.

"/        pack notNil ifTrue:[^ pack].

"/    ].

"/

"/    baseName := (Smalltalk fileNameForClass:nm) , '.rs'.

"/    rsrcDir := aClass resourceDirectory.

"/

"/"/ CHECK this

"/"/    (rsrcDir notNil and:[rsrcDir suffix = 'rs']) ifTrue:[

"/"/        baseName := (Smalltalk fileNameForClass: rsrcDir tail asFilename withoutSuffix pathName),'.rs'.

"/"/        rsrcDir := rsrcDir head asFilename.

"/"/    ].

"/

"/    rsrcDir notNil ifTrue:[

"/        pack := self new.

"/        rsrcDir exists ifTrue:[

"/            (rsrcDir construct:baseName) exists ifTrue:[

"/                pack := self fromFile:baseName directory:(rsrcDir name) cached:cached.

"/            ].

"/        ]

"/    ] ifFalse:[

"/        pack := self fromFile:baseName directory:'resources' cached:cached.

"/    ].

"/    aClass superclass notNil ifTrue:[

"/        pack superPack:(self for:(aClass superclass) cached:cached).

"/    ].

"/    pack packsClassOrFileName:nm.

"/    cached ifTrue:[

"/        self addToCache:pack.

"/    ].

"/    pack projectPack:(self forPackage:(aClass resourcePackage) cached:cached).

"/    ^ pack

    "

     ResourcePack forPackage:'bosch:dapasx' cached:true

     ResourcePack for:TextView

     ResourcePack for:CodeView

     ResourcePack for:Workspace

     ResourcePack for:View

     ResourcePack for:ErrorLogger

     ResourcePack for:NewLauncher

     Workspace classResources

    "

    "Modified: / 01-11-2010 / 09:09:43 / cg"

    "Modified: / 16-10-2018 / 17:12:25 / Stefan Vogel"

    "Modified (comment): / 15-03-2019 / 10:50:07 / Stefan Vogel"

!

forPackage:package

    "get the full resource definitions given a package id (such as stx:libbasic').

     Also leave the resulting pack in the cache for faster access next time."

    ^ self forPackage:package cached:true

    "

     ResourcePack forPackage:'stx:libbasic'

     ResourcePack forPackage:'stx:libtool'

     ResourcePack forPackage:'stx:libView'

    "

    "Modified: / 18-09-2006 / 18:45:31 / cg"

!

forPackage:package cached:cached

    "get the full resource definitions given a package id (such as stx:libbasic').

     Also optionally leave the resulting pack in the cache for faster access next time."

    |pack lang territory|

    pack := self forPackage:package resourceFileName:'resources.rs' cached:cached defaultIfAbsent:false.

    pack isNil ifTrue:[

        lang := Smalltalk language.

        territory := Smalltalk languageTerritory.

        pack := self forPackage:package resourceFileName:(lang,'_',territory,'.rs') cached:cached defaultIfAbsent:false.

        pack isNil ifTrue:[

            pack := self forPackage:package resourceFileName:(lang,'.rs') cached:cached defaultIfAbsent:false.

            pack isNil ifTrue:[

                pack := self newDefaultResourcePackForPackage:package.

                self addAdditionalSuperPacksForPackage:package to:pack.

            ].

        ]

    ].

    ^ pack

    "

     ResourcePack forPackage:'stx:libbasic' cached:false

     ResourcePack forPackage:'exept:expecco/plugin/windowsAutomation2' cached:false

    "

    "Modified: / 19-10-2006 / 23:18:28 / cg"

    "Modified: / 13-12-2018 / 13:24:56 / Claus Gittinger"

!

forPackage:package resourceFileName:resourceFileName cached:cached

    "get the full resource definitions given a package id (such as stx:libbasic').

     Also optionally leave the resulting pack in the cache for faster access next time.

     Remember failed packs, to avoid retrying reading the file again and again"

    ^ self

        forPackage:package 

        resourceFileName:resourceFileName 

        cached:cached 

        defaultIfAbsent:true

    "

     ResourcePack flushCachedResourcePacks.

     ResourcePack 

        forPackage:'stx:libbasic' 

        resourceFileName:'resources.rs' 

        cached:false

    "

    "Modified: / 28-09-2011 / 15:55:30 / cg"

    "Modified: / 13-12-2018 / 13:17:00 / Claus Gittinger"

!

forPackage:package resourceFileName:resourceFileName cached:cached defaultIfAbsent:defaultIfAbsentBoolean

    "get the full resource definitions given a package id (such as stx:libbasic').

     Also optionally leave the resulting pack in the cache for faster access next time.

     Remember failed packs, to avoid retrying reading the file again and again"

    |fullName pack rsrcDir file|

    package isNil ifTrue:[

        "/ '[ResourcePack] warning: nil package asking for resource file'.

        defaultIfAbsentBoolean ifFalse:[^ nil].

        ^ self newDefaultResourcePackForPackage:package

    ].

    fullName := (package copyReplaceAll:$: with:$/),'/resources/',resourceFileName.

    cached ifTrue:[

        pack := self searchCacheFor:fullName.

        pack notNil ifTrue:[^ pack].

        (FailedToLoadPacks includes:fullName) ifTrue:[

            "/ it already failed to load - do not try again

            defaultIfAbsentBoolean ifFalse:[^ nil].

            pack := self newDefaultResourcePackForPackage:package.

            self addAdditionalSuperPacksForPackage:package to:pack.

            ^ pack

        ].

    ].

    "/ Smalltalk projectDirectoryForPackage:'stx:libview'

    rsrcDir := Smalltalk projectDirectoryForPackage:package.

    "/ '1) projectDirectoryForPackage -> ' print.

    "/ rsrcDir printCR.

    rsrcDir notNil ifTrue:[

        rsrcDir := rsrcDir asFilename / 'resources'.

        "/ '3) rsrcDir -> ' print.

        "/ rsrcDir printCR.

        rsrcDir exists ifTrue:[

            (rsrcDir / resourceFileName) exists ifTrue:[

                pack := self fromFile:resourceFileName directory:rsrcDir cached:cached.

                pack packsPackage:package.

                self addAdditionalSuperPacksForPackage:package to:pack.

                ^ pack

            ].

        ].

    ].        

    file := Smalltalk getResourceFileName:resourceFileName forPackage:package.

    (file notNil and:[(file := file asFilename) exists]) ifTrue:[

        rsrcDir := file directory.

        pack := self fromFile:resourceFileName directory:rsrcDir cached:cached.

        pack packsPackage:package.

        self addAdditionalSuperPacksForPackage:package to:pack.

        ^ pack

    ].

    FailedToLoadPacks add:fullName.

    defaultIfAbsentBoolean ifFalse:[^ nil].

    pack := self newDefaultResourcePackForPackage:package.

    self addAdditionalSuperPacksForPackage:package to:pack.

    ^ pack

    "

     ResourcePack flushCachedResourcePacks.

     ResourcePack 

        forPackage:'stx:libbasic' 

        resourceFileName:'resources.rs' 

        cached:false

    "

    "Created: / 13-12-2018 / 13:16:36 / Claus Gittinger"

!